Code Focused

Take Advantage of XML Comments (Part 1)

Use XML comments to generate IntelliSense and custom documentation for your applications. Part 1 of this two-part series explores using standard XML comments to document your code within Visual Studio.

• By Joe Kunk
• 07/21/2011

XML comments provide a native means in Visual Studio, for both the Visual Basic and C# developer, to generate IntelliSense and custom documentation for source code elements. XML comments have existed in both languages since the release of Visual Studio 2005, yet many developers fail to take full advantage of their benefits. XML comments help speed development by providing IntelliSense on custom methods and other code constructs. XML comments encourage code reuse by providing a path to generate API style reference documentation from your source code.

In Part 1 of this article I discuss using standard XML comments to document your code within Visual Studio. In Part 2, I will discuss creating custom XML comment tags and processing the XML Comment output with an external tool.

Figure 1 shows a comparison of the XML comments implementation for both Visual Basic and C#, as provided by Visual Studio 2010. It is interesting to note that the Visual Basic editor is more descriptive by showing the contents of the Summary tag when the comment is collapsed, while C# shows only the Summary tag itself. C# shows the method's namespace in the IntelliSense prompt while Visual Basic does not. XML comments in Visual Basic are inserted by typing three apostrophes in a row on a blank line directly above the member definition, or at the start of the member definition and pressing enter. In C#, XML comments are initiated with three forward slashes.

The Visual Basic editor recognizes the code element's structure, such as the number and name of the parameters, and adjusts the XML Comment template block accordingly when added in the editor. Syntax is verified by the compiler. This is done only at the time that the XML Comment block is added; it is the developer's responsibility to update the XML Comment if the code element's structure changes, such as adding or removing a parameter or changing the return type of the function.

In Visual Basic, the compiler is always running in the background so that the IntelliSense from the XML Comment summary tag is available immediately without a Build action.

[Click on image for larger view.]

Figure 1. XML comments in both Visual Basic and C#

Enabling XML Comments
XML comments are enabled by default in Visual Basic projects, and cannot be disabled. To enable or disable XML comments for a specific project, go to the project properties page, the Compile tab, and update the "Generate XML documentation file" checkbox.

In C#, XML comments generation must be enabled in the Build tab of the project's properties page as shown in Figure 2. While I don't recommend it, XML comments can be disabled completely in the C# editor by going to Tools, Options, Advanced, and unchecking the XML Documentation Comments option "Generate XML documentation comments for ///."

Note that XML comments are not metadata and are not included in the compiled assembly. As a result, they are not accessible via reflection.

[Click on image for larger view.]

Figure 1. Enabling XML Comment output for C# projects

XML comments can be added to virtually any programming construct outside a method. Namespaces cannot use XML comments since they can span multiple assemblies and by definition, the XML comments file is output for a specific assembly. XML comments can be added for a partial class, but only at one instance (physical file location) of the partial class. There are no restrictions on using XML comments for the individual members of the partial class at each of its instances.

Standard XML Comment Tags
Visual Basic and C# both share the XML comment tags of c, code, description, example, exception, include, item, list, listheader, para, param, permission, remarks, returns, see, seealso, summary, term, typeparam and value.

The XML comments tags and their suggested usage are shown below.

c: Single line code sample.
code: Multiple-line code sample.
Description: Descriptive text of an item in a list or listheader.
example: Example usage. Often includes c and code tags.
exception: Indicates an exception that may be thrown by the method definition.
include: Specifies an external file with comments that describe the source code, using XML XPath syntax to specify the file path. This can be used as an alternative to inline comments. Example:
''' <include file="AppCommentFile.xml" path="Docs/Members[@name='ClassMemberName']/*"/>
item: An entry in a list or listheader. A list may contain any number of item tags.
list: A list of type "bullet", "number", or "table" (2 column table).
Listheader: Provides a header for a list.
para: For use within other tags, splits text up into paragraphs for better formatting.
param: Provides a description for the method parameter identified in the tag. Example:
''' <param name="ID">The primary key ID to retrieve.</param>
paramref: Refers to the method's arguments within the XML Comments block.
permission: Specifies a member or field accessible from the current.
remarks: Add supplemental information to that contained for in the summary tag.
returns: Descriptive text for the return value of a function.
see: References other elements within the project.
seealso: Provides text for a See Also section in the generated reference documentation.
summary: Provides IntelliSense text for the code element and serves as the container for most XML tags.
term: A glossary term to define with a description tag, used in list type of table.
typeparm: Used to describe the type parameters for a generic type or member declaration.
value: Descriptive text for the value of a property.

In Visual Basic, each code construct has the template summary and remarks tags that appear as soon as the XML comment indicator of triple-apostrophe (''') is typed above the code construct declaration. The top-level tags of include and permission are always available as well, though not provided automatically in the initial template.

Table 1 shows the additional top-level XML comment tags by code element. Each code element also supports multiple CompletionList tags, which are additional tags available within the XML comment text.

Table 1. Element Specific XML Comment Tags for Visual Basic

Some XML Comment tags contain attributes. The file, path, and cref attributes are resolved at compile time.

A number of XML comment tags appear in IntelliSense only as child elements of other tags. These tags, known as ChildCompletionList tags, are: c, code, example, list, listheader, para, paramref, see and seealso. Child elements of the the list or listheader tags are item, term and description.

Conclusion
XML Comments provide a rich vocabulary to add substantial descriptive information to source code elements in a structured manner. The text in the summary tag benefits both the original and subsequent developers by providing IntelliSense on custom code elements.

In Part 2, I will discuss creating custom XML comment tags in Visual Basic and processing the XML Comment output with an external tool to generate API style reference documentation.