Section 18.3. XML Documentation Comments

18.3. XML Documentation Comments

C# supports a new documentation comment style, with three slash marks ( /// ). You can see these comments sprinkled throughout Example 18-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 generate the documentation 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 Properties. Click the Build tab and then click the XML Documenation file and provide a path for where the XML should be placed, as shown in Figure 18-10.

Click the XML Documentation File checkbox and type in a name for the XML file you want to produce, such as Filecopier.XML. Rebuild the application.

In at least some versions of Visual C# 2005 Express, you accomplish this by clicking the Properties button in the Solution Explorer window. Please check the documentation for the version of Visual Studio 2005 you are using.

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

Figure 18-10. Setting the XML documentation path

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

 <?xml version="1.0"?> <doc>     <assembly>         <name>FileCopier</name>     </assembly>     <members>         <member name="T:FileCopier.frmFileCopier">             <summary>             Form demonstrating Windows Forms implementation             </summary>         </member>         <member name="M:FileCopier.frmFileCopier.FillDirectoryTree(System.Windows.Forms. TreeView,System.Boolean)">             <summary>             Factored out method for both directory trees             </summary>             <param name="tvw">which treeview called this handler</param>             <param name="isSource">get the files if true</param>         </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 18-11.

Figure 18-11. Reviewing the XML documentation in Internet Explorer

Internet Explorer provides a number of handy features for reading XML files, including the ability to expand and collapse nodes (see the + and - signs to the left of each node).