XML Comments

Chapter 1 introduced comments. However, you can use XML comments for more than just notes to other programmers reviewing the source code. XML-based comments follow a practice popularized with Java. Although the C# compiler ignores all comments as far as the resulting executable goes, the developer can use command-line options to instruct the compiler [1] to extract the XML comments into a separate XML file. By taking advantage of the XML file generation, the developer can generate documentation of the API from the XML comments. In addition, C# editors can parse the XML comments in the code and display them to developers as distinct regions (for example, as a different color from the rest of the code), or parse the XML comment data elements and display them to the developer.

[1] The C# standard does not specify whether the C# compiler or a separate utility takes care of extracting the XML data. However, all mainstream C# compilers include the functionality via a compile switch instead of within an additional utility.

Figure 9.2 demonstrates how an IDE can take advantage of XML comments to assist the developer with a tip about the code he is trying to write.

Figure 9.2. XML Comments as Tips in Visual Studio IDE

These coding tips offer significant assistance in large programs, especially when multiple developers share code. For this to work, however, the developer obviously must take the time to enter the XML comments within the code and then direct the compiler to create the XML file. The next section explains how to accomplish this. (See Listing 9.17.)

Associating XML Comments with Programming Constructs

Consider the listing of the DataStorage class, as shown in Listing 9.17.

Listing 9.17. Commenting Code with XML Comments

Listing 9.17 uses both XML delimited comments that span multiple lines, and single-line XML comments where each line requires a separate three-forward-slash delimiter (///).

Since XML comments are designed to document the API, they are intended for use only in association with C# declarations, such as the class or method shown in Listing 9.17. Any attempt to place an XML comment inline with the code, unassociated with a declaration, will result in a warning by the compiler. The compile makes the association simply because the XML comment appears immediately before the declaration.

Although C# allows any XML tag in comments, the C# standard explicitly defines a set of tags to be used. <seealso cref="System.IO.StreamWriter"/> is an example of using the seealso tag. This tag creates a link between the text and the System.IO.StreamWriter class.

Generating an XML Documentation File

The compiler will check that the XML comments are well formed, and will issue a warning if they are not. To generate the XML file, you need to use the /doc option when compiling, as shown in Output 9.8.

Output 9.8.

>csc /doc:Comments.xml DataStorage.cs

The /doc option will create an XML file based on the name specified after the colon. Using the DataStorage class shown in Listing 9.17 and the compiler options listed here, the resulting CommentSamples.XML file appears as shown in Listing 9.18.

Listing 9.18. Comments.xml

<?xml version="1.0"?> <doc>     <assembly>         <name>DataStorage</name>     </assembly>     <members>         <member name="T:DataStorage">             <summary>             DataStorage is used to persist and retrieve employee data from the files.             </summary>         </member>         <member name="M:DataStorage.Store(Employee)">             <summary>             Save an employee object to a file named with the Employee name.             </summary>             <remarks>             This method uses             <seealso cref="T:System.IO.FileStream"/>             in addition to             <seealso cref="T:System.IO.StreamWriter"/>             </remarks>             <param name="employee">             The employee to persist to a vile</param>             <date>January 1, 2000</date>         </member>         <member name="M:DataStorage.Load(System.String,System.String)">             <summary>             Loads up an employee object             </summary>             <remarks>             This method uses             <seealso cref="T:System.IO.FileStream"/>             in addition to             <seealso cref="T:System.IO.StreamReader"/>             </remarks>             <param name="firstName">             The first name of the employee</param>             <param name="lastName">             The last name of the employee</param>             <returns>             The employee object corresponding to the names             </returns>             <date>January 1, 2000</date>*         </member>         </members> </doc>

The resulting file includes only the amount of metadata that is necessary to associate an element back to its corresponding C# declaration. This is important to note, because in general, it is necessary to use the XML output in combination with the generated assembly in order to produce any meaningful documentation. Fortunately, tools such as the open source project NDoc [2] can generate documentation.

[2] See http://ndoc.sourceforge.net to learn more about this tool.

Essential C# 2.0
Essential C# 2.0
ISBN: 0321150775
EAN: 2147483647
Year: 2007
Pages: 185

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net