CHAPTER 25 ■ OTHER TOPICS

Documentation Comments

The dcumentation comments feature allows you to include documentation of your program in the form of XML elements. Visual Studio even assists you in inserting the elements and will read them from your source file and copy them to a separate XML file for you. This section does not cover the topic of XML but presents the overall process of using documentation comments.

Figure 25-5 gives an overview of using XML comments. This includes the following steps:

•You can use Visual Studio to produce the source file with the embedded XML. Visual Studio can automatically insert most of the important XML elements.

•Visual Studio reads the XML from the source code file and copies the XML code to a new file.

•Another program, called a documentation compiler, can take the XML file and produce various types of documentation files from it.

Figure 25-5. The XML comments process

Earlier versions of Visual Studio contained an elementary documentation compiler, but it was removed before the release of Visual Studio 2005. Microsoft has developed a new documentation compiler called Sandcastle, which they already use to generate the .NET Framework documentation. You can learn more about it and download it for free from http://sandcastle.codeplex.com.

681

CHAPTER 25 ■ OTHER TOPICS

Inserting Documentation Comments

Documentation comments start with three consecutive forward slashes.

•The first two slashes indicate to the compiler that this is an end-of-line comment and should be ignored in the parsing of the program.

•The third slash indicates that it’s a documentation comment.

For example, in the following code, the first four lines show documentation comments about the class declaration. They use the <summary> XML tag. Above the declaration of the field are three lines documenting the field—again using the <summary> tag.

///<summary> ← Open XML tag for the class

///This is class MyClass, which does the following wonderful things, using

///the following algorithm. ... Besides those, it does these additional

///wonderful things.

///<summary> ← Open XML tag for the field

///Field1 is used to hold the value of ...

///</summary> ← Close XML tag

Each XML element is inserted by Visual Studio automatically when you type three slashes above the declaration of a language feature, such as a class or a class member.

For example, the following code shows two slashes above the declaration of class MyClass:

//

class MyClass { ...

As soon as you add the third slash, Visual Studio immediately expands the comment to the following code, without your having to do anything. You can then type anything you want on the documentation comment lines between the tags.

682

CHAPTER 25 ■ OTHER TOPICS

Using Other XML Tags

In the preceding examples, you saw the use of the summary XML tag. There are also a number of other tags that C# recognizes. Table 25-3 lists some of the most important.

Table 25-3. Documentation Code XML Tags

Tag Meaning

<example> Mark the enclosing lines as an example.

<param> Mark a parameter for a method or constructor and allow a description.

<remarks> Describe a type declaration.

<returns> Describe a return value.

<seealso> Create a See Also entry in the output document.

<summary> Describe a type or a type member.

<value> Describe a property.

683