XML Comments

Chapter 1 introduced comments. However, you can use XML comments for more than just notes to other developers reviewing the source code. XML-based comments follow a practice popularized with Java. Although the C# compiler ignores all comments as far as the resultant executable goes, the developer can use command-line options to instruct the compiler5 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 (e.g., as a different color from the rest of the code) or parse the XML comment data elements and display them to the developer.

Figure 10.3 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. Such 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.

Figure 10.3: XML comments as tips in Visual Studio IDE

Starting with Visual Studio 2019, you can also embed simple HTML into a comment, and it will be reflected in the tips. For example, surrounding console with <strong> and </strong> will cause the word “console” to display in bold in Figure 10.3.

Associating XML Comments with Programming Constructs

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

Listing 10.12: Commenting Code with XML Comments
1. /// <summary>
2. /// DataStorage is used to persist and retrieve
3. /// employee data from the files.
4. /// </summary>
5. class DataStorage
6. {
7.     /// <summary>
8.     /// Save an employee object to a file
9.     /// named with the Employee name.
10.     /// </summary>
11.     /// <remarks>
12.     /// This method uses <seealso cref="System.IO.FileStream"/>
13.     /// in addition to
14.     /// <seealso cref="System.IO.StreamWriter"/>
15.     /// </remarks>
16.     /// <param name="employee">
17.     /// The employee to persist to a file</param>
18.     /// <date>January 1, 2000</date>
19.     public static void Store(Employee employee)
20.     {
21.         // ...
22.     }
23.  
24.     /** <summary>
25.      * Loads up an employee object.
26.      * </summary>
27.      * <remarks>
28.      * This method uses <seealso cref="System.IO.FileStream"/>
29.      * in addition to
30.      * <seealso cref="System.IO.StreamReader"/>
31.      * </remarks>
32.      * <param name="firstName">
33.      * The first name of the employee</param>
34.      * <param name="lastName">
35.      * The last name of the employee</param>
36.      * <returns>
37.      * The employee object corresponding to the names
38.      * </returns>
39.      * <date>January 1, 2000</date> **/
40.     public static Employee Load(string firstName, string lastName)
41.     {
42.         // ...
43.     }
44. }
45.  
46. class Program
47. {
48.     // ...
49. }

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

Given that 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 10.12. Any attempt to place an XML comment inline with the code, unassociated with a declaration, will result in a warning by the compiler. The compiler makes the association simply because the XML comment appears immediately before the declaration.

Although C# allows any XML tag to appear 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 checks that the XML comments are well formed and issues a warning if they are not. To generate the XML file, add a DocumentationFile element to the ProjectProperties element:

<DocumentationFile>$(OutputPath)\$(TargetFramework)\$(AssemblyName).xml

</DocumentationFile>

This element causes an XML file to be generated during the build into the output directory using the <assemblyname>.xml as the filename. Using the CommentSamples class listed earlier and the compiler options listed here, the resultant CommentSamples.XML file appears as shown in Listing 10.13.

Listing 10.13: Comments.xml
1. <?xml version="1.0"?>
2. <doc>
3.     <assembly>
4.         <name>DataStorage</name>
5.     </assembly>
6.     <members>
7.         <member name="T:DataStorage">
8.             <summary>
9.                 DataStorage is used to persist and retrieve
10.                 employee data from the files.
11.             </summary>
12.         </member>
13.         <member name="M:DataStorage.Store(Employee)">
14.             <summary>
15.                 Save an employee object to a file
16.                 named with the Employee name.
17.             </summary>
18.             <remarks>
19.                 This method uses
20.                 <seealso cref="T:System.IO.FileStream"/>
21.                 in addition to
22.                 <seealso cref="T:System.IO.StreamWriter"/>
23.             </remarks>
24.             <param name="employee">
25.                 The employee to persist to a file
26.             </param>
27.             <date>January 1, 2000</date>
28.         </member>
29.         <member name="M:DataStorage.Load(
30.                  System.String,System.String)">
31.             <summary>
32.                 Loads up an employee object
33.             </summary>
34.             <remarks>
35.                 This method uses
36.                 <seealso cref="T:System.IO.FileStream"/>
37.                 in addition to
38.                 <seealso cref="T:System.IO.StreamReader"/>
39.             </remarks>
40.             <param name="firstName">
41.                 The first name of the employee
42.             </param>
43.             <param name="lastName">
44.                 The last name of the employee
45.             </param>
46.             <returns>
47.                 The employee object corresponding to the names
48.             </returns>
49.             <date>January 1, 2000</date>*
50.         </member>
51.     </members>
52. </doc>

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

Guidelines
DO provide XML comments on public APIs when they provide more context than the API signature alone. This includes member descriptions, parameter descriptions, and examples of calling the API.

________________________________________

5. The C# standard does not specify whether the C# compiler or a separate utility should take care of extracting the XML data. However, all mainstream C# compilers include the necessary functionality via a compile switch instead of within an additional utility.
6. See https://submain.com/ to learn more about GhostDoc.
7. See https://ndoc.sourceforge.net/ to learn more about NDoc.
{{ snackbarMessage }}
;