XML documentation in C #

Greetings, habra-donetchiki!

Today we will discuss one interesting and useful feature of the C # language, which will help us in documenting the code. It is called "XML documentation" or "XML documenting comments". These are special XML tags that are contained in comments and describe properties or methods in a particular file. So, there are at least three good reasons why you should always fill out XML comments.





First, this approach allows you to standardize comments in your project and, in principle, in all projects in C #, and the standards in our business are almost always good. Secondly, IntelliSense will automatically display information about the documented methods and parameters, as well as for the methods built into the framework. This will greatly facilitate the work and save time, and 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 with this file you can do anything.



And now we consider the tags recommended for use. In order to start entering them, you must first put "///".

')

Tag	Is used for
<c>	one line of source code
<code>	many lines of source code
<example>	usage example, can be used with the <code> tag
<exception>	allows you to specify which exceptions our method may throw
<include>	allows you to link to a file containing comments using XPath
<list>	regular list
<para>	This is a regular paragraph.
<param>	method parameter descriptions, each parameter is described separately
<paramref>	allows you to specify that the word inside the tag is a parameter
<permission>	allows to describe access rights to the method
<remarks>	additional information besides the <summary> tag
<returns>	description of what the method returns
<see>	allows you to specify links
<seealso>	text in the "See also" section
<summary>	general description
<value>	allows you to describe properties

Example:

/// <summary>

/// , .

/// </summary>

/// <param name="repeat"> </param>

/// <returns> </returns>

public string HelloHabr( int repeat)

{

string result = "" ;

for ( int i = 0; i < repeat; i++)

{

result += "Hello, HabraHabr!\n" ;

}

return result;

}





And this is how our method will be shown in IntelliSense:







Details about everything can be read as always on MSDN .



Well, for starters, probably everything. Start documenting your code correctly for now, and I will prepare a couple more articles on this topic if this one turns out to be relevant.