Herbert Schildt - C# 3.0 the Complete Reference 3/E (Complete Reference Series)

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 */. The lines after the /** can (but are not required to) start with a single *. If all subsequent lines in the multiline comment begin with a *, the * is ignored.

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 . 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 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:

name
text

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

item-name
text

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

Tag	Description
code	Specifies the text specified by code as program code.
code	Specifies multiple lines of text specified by code as program code.
explanation	The text associated with explanation describes a code example.
explanation	Describes an exception. The exception is specified by name.
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-header list-items	Specifies a list. The type of the list is specified by type, which must be either bullet, number, or table.
text	Specifies a paragraph of text within another tag.
param-name> explanation	Documents the parameter specified by param-name. The text associated with explanation describes the parameter.
Specifies that param-name is a parameter name.
explanation	Describes the permission setting associated with the class members specified by identifier. The text associated with explanation describes the permission settings.
explanation	The text specified by explanation is a general commentary often used to describe a type, such as a class or structure.
explanation	The text specified by explanation documents the return value of a method.
Declares a link to another element specified by identifier.
Declares a "see also" link to identifier.
explanation	The text specified by explanation is a general commentary often used to describe a method or other class member.
explanation	Documents the type parameter specified by param-name. The text associated with explanation describes the type parameter.
Specifies that param-name is the name of a type parameter.
explanation	The text specified by explanation documents a property.

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 2008 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;
/**
This is an example of multiline XML documentation.
The Test class demonstrates several tags.
*/
class Test {
///

/// Main is where execution begins.
///
static void Main() {
int sum;
sum = Summation(5);
Console.WriteLine("Summation of " + 5 + " is " + sum);
}
///
/// Summation returns the summation of its argument.
///
/// The value to be summed is passed in val.
///
///
///
/// The summation is returned as an int value.
///
///
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:

DocTest
This is an example of multiline XML documentation.
The Test class demonstrates several tags.

Main is where execution begins.
Summation returns the summation of its argument.
The value to be summed is passed in val.
The summation is returned as an int value.

Notice that each documented element is given a unique identifier. These identifiers can be used by other programs that use the XML documentation.

C# is Microsofts premier language for .NET development. It leverages time-tested features with cutting-edge innovations and provides a highly usable, efficient way to write programs for the modern enterprise computing environment. It is, by any measure, one of the most important languages of the 21st century.

The purpose of this chapter is to place C# into its historical context, including the forces that drove its creation, its design philosophy, and how it was influenced by other computer languages. This chapter also explains how C# relates to the .NET Framework. As you will see, C# and the .NET Framework work together to create a highly refined programming environment.