Section 13.3. XML Documentation Comments

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-1. The Visual Studio 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-1 with this command line:

csc Form1.cs /doc:XMLDoc.XML

You can accomplish this same operation in Visual Studio by clicking the FileCopier project icon in the Solution Explorer window, selecting View Property Pages on the Visual Studio menu, and then clicking Build property page. Click the XMLDocumentation File checkbox and type in a name for the XML file you want to produce, e.g., Filecopier.XML .

An excerpt of the file that's produced for the FileCopier application of the previous section is shown in Example 13-2.

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

<doc>     <assembly>         <name>FileCopier</name>     </assembly>     <members>         <member name="T:FileCopier.frmFileCopier">             <summary>             Form demonstrating Windows Forms implementation             </summary>         </member>         <member name="F:FileCopier.frmFileCopier.components">             <summary>             Required designer variable.             </summary>         </member>         <member name="M:FileCopier.frmFileCopier.Dispose(System.          Boolean)">             <summary>             Clean up any resources being used.             </summary>         </member>         <member name="M:FileCopier.frmFileCopier.InitializeComponent">             <summary>             Required method for Designer support - do not modify             the contents of this method with the code editor.             </summary>         </member>         <member name="M:FileCopier.frmFileCopier.GetSubDirectoryNodes          (System.Windows.Forms.TreeNode,System.String,System.Boolean,           System.Int32)">             <summary>             Gets all the subdirectories below the              passed in directory node.             Adds to the directory tree.             The parameters passed in are the parent node              for this subdirectory,             the full path name of this subdirectory,              and a Boolean to indicate             whether or not to get the files in the subdirectory.             </summary>         </member>         <member name="M:FileCopier.frmFileCopier.btnCopy_Click                 (System.Object,System.EventArgs)">                <summary>                Create an ordered list of all                 the selected files, copy to the                target directory             </summary>         </member>

The file is quite long, and although it can be read by humans, it isn't 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. You can also drag the file from File Explorer into Windows Explorer, which provides a nice interface for reading the XML, as shown in Figure 13-9.

Figure 13-9. Reviewing the XML documentation in Internet Explorer