The first step you should take is to become familiar with the XML tags used in the documentation process. The following tags are a recommendation from Microsoft for the documentation comments. Keep in mind that these tags are only a recommendation. However, the tags listed below should prove to be valuable during the documentation process. You can also utilize any custom tag that is valid XML, as the compiler will process any such tag, and there are products out there that take advantage of this. One such product is NDoc, which I will discuss a little later.
Figure 1: Recommended XML Documentation Tags
|
Tag |
Description |
|
<c> |
The <c> tag gives you a way to indicate that text within a description should be marked as code. |
|
<code> |
The <code> tag gives you a way to indicate multiple lines as code. |
|
<example> |
The <example> tag lets you specify an example of how to use a method or other library member. |
|
<exception> |
The <exception> tag lets you specify which exceptions can be thrown. |
|
<include> |
The <include> tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file. |
|
<listheader> |
The <listheader> block is used to define the heading row of either a table or definition list. |
|
<para> |
The <para> tag is for use inside another tag, such as <summary>, <remarks>, or <returns>, and lets you add structure to the text. |
|
<param> |
The <param> tag should be used in the comment for a method declaration to describe one of the parameters for the method. The text for the <param> tag will be displayed in IntelliSense, the Object Browser, and in the Code Comment Web Report. |
|
<paramref> |
The <paramref> tag gives you a way to indicate that a word is a parameter. |
|
<permission> |
The <permission> tag lets you document the access of a member. |
|
<remarks> |
The <remarks> tag is used to add information about a type, supplementing the information specified with <summary>. This information is displayed in the Object Browser and in the Code Comment Web Report. |
|
<returns> |
The <returns> tag should be used in the comment for a method declaration to describe the return value. |
|
<see> |
The <see> tag lets you specify a link from within text. |
|
<seealso> |
The <seealso> tag lets you specify the text that you might want to appear in a See Also section. |
|
<summary> |
The <summary> tag should be used to describe a type or a type member. Use <remarks> to add supplemental information to a type description. The text for the <summary> tag is the only source of information about the type in IntelliSense, and is also displayed in the Object Browser and in the Code Comment Web Report. |
|
<value> |
The <value> tag lets you describe a property. Note that when you add a property via code wizard in the Visual Studio .NET development environment, it will add a <summary> tag for the new property. You should then manually add a <value> tag to describe the value that the property represents. |
MSDN: C# Programmer's Reference: Recommended Tags for Documentation Comments
