13.3 XML Documentation Comments

C# supports a new documentation comment style, with three slash marks (///). You can see these comments sprinkled throughout Example 13-3. The Visual Studio .NET editor recognizes these comments and helps format them properly.

The C# compiler processes these comments into an XML file. You can create this file by using the /doc command-line switch. For example, you might compile the program in Example 13-3 with this command line:

csc Form1.cs /doc:XMLDoc.XML

You can accomplish this same operation in Visual Studio .NET by clicking the FileCopier project icon in the Solution Explorer window, selecting View Property Pages on the Visual Studio menu, and then clicking the Configuration Properties folder. Within the Configuration Properties folder, click the Build property page and type in a name for the XML Documentation File property to specify a name for the XML file you want to produce.

Either approach produces the file XMLDoc.XML with your comments in XML format. An excerpt of the file that will be produced for the FileCopier application of the previous section is shown in Example 13-4.

Example 13-4. The XML output (excerpt) for file copy

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>FileCopier</name>
    </assembly>
    <members>
        <member name="T:FileCopier.Form1">
            <summary>
            Form demonstrating Windows Forms implementation
            </summary>
        </member>
        <member name="F:FileCopier.Form1.components">
            <summary>
            Required designer variable.
            </summary>
        </member>
        <member name="F:FileCopier.Form1.tvwTargetDir">
            <summary>
              Tree view of potential target directories
            </summary>
        </member>
        <member name="F:FileCopier.Form1.tvwSource">
            <summary>
               Tree view of source directories
               includes check boxes for checking
               chosen files or directories
            </summary>
        </member>
        <member name="F:FileCopier.Form1.txtTargetDir">

The file is quite long, and although it can be read by humans, it is not especially useful in that format. You could, however, write an XSLT file to translate the XML into HTML, or you could read the XML document into a database of documentation.

One of the simplest things to do with the documentation comments in your source code is to allow Visual Studio to generate a Code Comment Web Report. You choose this from the Tools menu (Tools, Build Comment Web Pages . . . ), and the IDE does the rest. The result is a set of HTML files that you can view from within the IDE or from a browser, as shown in Figure 13-9.

Figure 13-9. Code comment web report

Every member preceded by a documentation comment is included in the XML file via a <member> tag added by the compiler, along with a name attribute that identifies the member. You can also make use of predefined tags to increase the richness of the generated documentation. For example, you can add <see> comments to reference another member in the class or <exception> to document exception classes. A detailed discussion of XML documentation comments is beyond the scope of this book, but a complete listing of available tags can be found in the C# Programmers Reference that is included with Visual Studio.