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.
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 IDEThese 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 ConstructsConsider 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 FileThe 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.
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
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.
|