Appendix A: XML Comment Quick Reference

C# supports three types of comments. The first two are // and /* */. The third type is based on XML tags and is called an XML comment. (XML comments are also called documentation comments.) A single-line XML comment begins with ///. A multiline XML comment begins with /** and ends with */. XML comments precede the declaration of such things as classes, namespaces, methods, properties, and events. Using XML comments, you can embed information about your program into the program itself. When you compile the program, you can have the XML comments placed into an XML file. XML comments can also be utilized by the IntelliSense feature of Visual Studio.

The XML Comment Tags

C# supports the XML documentation tags shown in Table A-1. Most of the XML comment tags are readily understandable, and they work like all other XML tags with which most programmers are already familiar. However, the <list> tag is more complicated than the others. A list contains two components: a list header and list items. The general form of a list header is shown here:

 <listheader>     <term> name </term>     <description> text </description> </listheader>

Here, text describes name. For a table, text is not used. The general form of a list item is shown next:

 <item>     <term> item-name </term>     <description> text </description> </item>

Here, text describes item-name. For bulleted or numbered lists, or tables, item-name is not used. There can be multiple <item> entries.

Table A-1: The XML Comment Tags

Tag	Description
<c> code </c>	Specifies the text specified by code as program code.
<code> code </code>	Specifies multiple lines of text specified by code as program code.
<example> explanation </example>	The text associated with explanation describes a code example.
<exception cref = “name”> explanation </exception>	Describes an exception. The exception is specified by name.
<include file = ‘fname’ path = ‘path [@tagName = “tagID”]’ />	Specifies a file that contains the XML comments for the current file. The file is specified by fname. The path to the tag, the tag name, and the tag ID are specified by path, tagName, and tagID, respectively.
<list type = “type”> list-header list-items </list>	Specifies a list. The type of the list is specified by type, which must be a bullet, number, or table.
<para> text </para>	Specifies a paragraph of text within another tag.
<param name = ‘param-name’> explanation </param>	Documents the parameter specified by param-name. The text associated with explanation describes the parameter.
<paramref name = “param-name” />	Specifies that param-name is a parameter name.
<permission cref = “identifier”> explanation </permission>	Describes the permission setting associated with the class members specified by identifier. The text associated with explanation describes the permission settings.
<remarks> explanation </remarks>	The text specified by explanation is a general commentary often used to describe a type, such as a class or structure.
<returns> explanation </returns>	The text specified by explanation documents the return value of a method.
<see cref = “identifier” />	Declares a link to another element, specified by identifier.
<seealso cref = “identifier” />	Declares a “see also” link to identifier.
<summary> explanation </summary>	The text specified by explanation is a general commentary often used to describe a method or other class member.
<typeparam name = “param-name”> explanation </typeparam>	Documents the type parameter specified by param-name. The text associated with explanation describes the type parameter. (Added by C# 2.0.)
<typeparamref name = “param-name”/>	Specifies that param-name is the name of a type parameter. (Added by C# 2.0.)
<value> explanation </value>	The text specified by explanation documents a property.