October 3, 2008 at 00:17XML documentation in C #
Greetings, Habr-donors!
Today we will talk about one interesting and useful feature of the C # language, which will help us in documenting the code. It is called XML Documentation or XML Documentation Comments. These are special XML tags that are contained in the comments and describe the properties or methods in a particular file. So, there are at least three good reasons why you should always populate XML comments.
Firstly, this approach allows you to standardize comments in your project and, in principle, in all C # projects, and the standards in our business are almost always good. Secondly, IntelliSense will automatically display information about documented methods and parameters, as well as for methods built into the framework. This will greatly facilitate the work and save time for you and other developers working with you. And thirdly, at the compilation stage, you can generate an XML file that will contain all the comments in a convenient format, and you can already do anything with this file.
Now we’ll review the recommended tags for use. In order to start entering them, you must first put "///".
Example:
And here is how our method will be shown in IntelliSense:
Details about everything can be read as always on MSDN .
Well, for starters, probably all. Begin by documenting your code correctly, and I will prepare a couple more articles on this topic, if this turns out to be relevant.
Today we will talk about one interesting and useful feature of the C # language, which will help us in documenting the code. It is called XML Documentation or XML Documentation Comments. These are special XML tags that are contained in the comments and describe the properties or methods in a particular file. So, there are at least three good reasons why you should always populate XML comments.
Firstly, this approach allows you to standardize comments in your project and, in principle, in all C # projects, and the standards in our business are almost always good. Secondly, IntelliSense will automatically display information about documented methods and parameters, as well as for methods built into the framework. This will greatly facilitate the work and save time for you and other developers working with you. And thirdly, at the compilation stage, you can generate an XML file that will contain all the comments in a convenient format, and you can already do anything with this file.
Now we’ll review the recommended tags for use. In order to start entering them, you must first put "///".
| Tag | Is used for |
| one line of source code | |
| many lines of source code |
usage example, can be used with tag | |
| allows you to specify which exceptions our method can throw | |
| allows you to put a link to a file that contains comments using XPath | |
| regular list | |
| and this is a regular paragraph | |
| method parameter descriptions, each parameter is described separately | |
| allows you to specify that the word inside the tag is a parameter | |
| allows you to describe the access rights to the method | |
| additional information besides tag | |
| a description of what the method returns | |
| allows you to specify links | |
| text in the section “See also” | |
| general description | |
| allows you to describe properties |
Example:
///
/// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
///
/// Сколько раз передать привет
/// Сама строка с приветами
public string HelloHabr(int repeat)
{
string result = "";
for (int i = 0; i < repeat; i++)
{
result += "Hello, HabraHabr!\n";
}
return result;
}
And here is how our method will be shown in IntelliSense:
Details about everything can be read as always on MSDN .
Well, for starters, probably all. Begin by documenting your code correctly, and I will prepare a couple more articles on this topic, if this turns out to be relevant.