C# supports three types of comments. The first two are // and /* */. The third type is based on XML tags and is called a documentation comment. (The term XML comment is also commonly used.) A single-line documentation comment begins with ///. A multiline documentation comment begins with /** and ends with */.
Documentation comments precede the declaration of such things as classes, namespaces, methods, properties, and events. Using documentation comments, you can embed information about your program into the program itself. When you compile the program, you can have the documentation comments placed into an XML file. Documentation comments can also be utilized by the IntelliSense feature of Visual Studio.
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
To produce an XML file that contains the documentation comments, specify the /doc option. For example, to compile a file called DocTest.cs that contains XML comments, use this command line:
csc DocTest.cs /doc:DocTest.xml
To create an XML output file when using the Visual Studio IDE, you must activate the Properties page. Next, select Build. Then, check the XML Documentation File box and specify the name of the XML file.
Here is an example that demonstrates several documentation comments. It uses both the multiline and the single-line forms. As a point of interest, many programmers use a series of single-line documentation comments rather than a multiline comment even when a comment spans several lines. (Several of the comments in this example use this approach.) The advantage is that it clearly identifies each line in a longer documentation comment as being part of a documentation comment. This is, of course, a stylistic issue, but it is common practice.
// A documentation comment example.
using System;
/** <remark>
This is an example of multiline XML documentation.
The Test class demonstrates several tags.
</remark>
*/
class Test {
/// <summary>
/// Main is where execution begins.
/// </summary>
static void Main() {
int sum;
sum = Summation(5);
Console.WriteLine("Summation of " + 5 + " is " + sum);
}
/// <summary>
/// Summation returns the summation of its argument.
/// <param name = "val">
/// The value to be summed is passed in val.
/// </param>
/// <see cref="int"> </see>
/// <returns>
/// The summation is returned as an int value.
/// </returns>
/// </summary>
static int Summation(int val) {
int result = 0;
for(int i=1; i <= val; i++)
result += i;
return result;
}
}
Assuming the preceding program is called XmlTest.cs, the following line will compile the program and produce a file called XmlTest.xml that contains the comments:
csc XmlTest.cs /doc:XmlTest.xml
After compiling, the following XML file is produced:
<?xml version="1.0"?>
<doc>
<assembly>
<name>DocTest</name>
</assembly>
<members>
<member name="T:Test">
<remark>
This is an example of multiline XML documentation.
The Test class demonstrates several tags.
</remark>
</member>
<member name="M:Test.Main">
<summary>
Main is where execution begins.
</summary>
</member>
<member name="M:Test.Summation(System.Int32)">
<summary>
Summation returns the summation of its argument.
<param name="val">
The value to be summed is passed in val.
</param>
<see cref="T:System.Int32"> </see>
<returns>
The summation is returned as an int value.
</returns>
</summary>
</member>
</members>
</doc>
Notice that each documented element is given a unique identifier. These identifiers can be used by other programs that use the XML documentation.