Visual Basic 2005: A Developer's Notebook

Create XML Documentation for Your Code

Properly commenting and documenting code takes time. Unfortunately, there's no easy way to leverage the descriptive comments you place in your code when it comes time to produce more detailed API references and documentation. Instead, you typically must create these documents from scratch.

Note

Use XML comments to effortlessly create detailed code references,a feature C# programmers have had since . NET 1.0.

Visual Studio 2005 changes all this by introducing a feature that's been taken for granted by C# programmers since .NET 1.0—XML comments. With XML comments, you comment your code using a predefined format. Then, you can use other tools to extract these comments and use them to build other documents. These documents can range from help documentation to specialized code reports (for example, a list of unresolved issues, legacy code, or code review dates).

How do I do that?

XML comments are distinguished from ordinary comments by their format. First of all, XML comments start with three apostrophes (rather than just one). Here's an example:

''' <summary>This is the summary.</summary>

As you can see, XML comments also have another characteristic—they use tag names. The tag identifies the type of comment. These tags allow you to distinguish between summary information, information about a specific method, references to other documentation sections, and so on.

The most commonly used XML comment tags include:

<summary>

Describes a class or another type. This is the highest-level information for your code.

<remarks>

Allows you to supplement the summary information. This tag is most commonly used to give a high-level description of each type member (e.g., individual methods and properties).

<param>

Describes the parameters accepted by a method. Add one <param> tag for each parameter.

<returns>

Describes the return value of a method.

<exception>

Allows you to specify which exceptions a class can throw.

<example>

Lets you specify an example of how to use a method or other member.

<see>

Allows you to create a link to another documentation element.

In addition, there are tags that are usually used just to format or structure blocks of text. You use these tags inside the other tags. They include:

<para>

Lets you add structure to a tag (such as a <remarks> tag) by separating its content into paragraphs.

<list>

Starts a bulleted list. You must tag each individual list item with the <item> tag.

<c>

Indicates that text within a description should be marked as code. Use the <code> tag to indicate multiple lines as code.

<code>

Allows you to embed multiple lines of code, as in an example of usage. For example, you would commonly put a <code> tag inside an <example> tag.

In addition, you can define custom tags that you can then use for your own purposes.

Visual Studio helps you out by automatically adding some XML tags—but only when you want them. For example, consider the code routine shown here, which tests if two files are exactly the same using a hash code. In order to use this sample as written, you need to import the System.IO and System.Security.Cryptography namespaces:

Public Function TestIfTwoFilesMatch(ByVal fileA As String, _
  ByVal fileB As String) As Boolean
    
    ' Create the hashing object.
    Dim Hash As HashAlgorithm = HashAlgorithm.Create( )
    
    ' Calculate the hash for the first file.
    Dim fsA As New FileStream(fileA, FileMode.Open)
    Dim HashA( ) As Byte = Hash.ComputeHash(fsA)
    fsA.Close( )
    
    ' Calculate the hash for the second file.
    Dim fsB As New FileStream(fileB, FileMode.Open)
    Dim HashB( ) As Byte = Hash.ComputeHash(fsB)
    fsB.Close( )
    
    ' Compare the hashes.
    Return (Convert.ToString(HashA) = Convert.ToString(HashB))
    
End Function

Now, position your cursor just before the function declaration, and insert three apostrophes. Visual Studio will automatically add a skeleton set of XML tags, as shown here:

''' <summary>
''' 
''' </summary>
''' <param name="fileA"></param>
''' <param name="fileB"></param>
''' <returns></returns>
''' <remarks></remarks>
Public Function TestIfTwoFilesMatch(ByVal fileA As String, _
  ByVal fileB As String) As Boolean
...

Now, you simply need to fill in some sample content within the tags:

''' <summary>
''' This function tests whether two files
''' contain the exact same content.
''' </summary>
''' <param name="fileA">Contains the full path to the first file.</param>
''' <param name="fileB">Contains the full path to the second file.</param>
''' <returns>True if the files match, false if they don't.</returns>
''' <remarks>
''' The implementation of this method uses cryptographic classes
''' to compute a hash value. This may not be the most performant
''' approach, but it is sensitive to the minutest differences,
''' and can't be practically fooled.
''' </remarks>

To make a more realistic example, put the TestIfTwoFilesMatch( ) method into a class, and add XML documentation tags to the class declaration. Here's a typical example, which uses cross-references that point to the available methods in a list:

''' <summary>
''' This class contains methods for comparing files.
''' </summary>
''' <remarks>
'''        <para>This class is stateless. However, it's not safe to use
''' it if the file in question may already be help open by another
''' process.</para>
'''        <para>The methods in this class include:</para>
'''        <list type="bullet">
'''            <item><see cref="FileComparer.TestIfTwoFilesMatch"/>
''' TestifTwoFilesMatch( ) uses hash codes to compare two files.</item>
'''        </list>
''' </remarks>
Public Class FileComparer
   ...
End Class

Unlike other comments, XML comments are added to the metadata of your compiled assembly. They'll automatically appear in the Object Browser when you examine a type.

Additionally, once you've created your XML tags, you can export them to an XML document. Just double-click the My Project node in the Solution Explorer, choose the Compile tab, and ensure that the "Generate XML documentation file" option is selected. The XML documentation is automatically saved into an XML file with the same name as your project and the extension .xml (in the bin directory).

The generated document will include all of the XML comments, with none of the code. You can then feed this document into some other type of application. For example, you might create your own custom application to scan XML comment files and build specialized reports.

What about...

...creating help documentation? Although Visual Studio 2005 doesn't include any tools of its own, the open source NDoc application provides a solution (http://ndoc.sourceforge.net). NDoc scans code and uses the XML documentation tags it finds to build MSDN-style web pages or Visual Studio-style (MS Help 2.0) documentation. At the time of this writing, NDoc doesn't yet support .NET 2.0.

Where can I learn more?

The MSDN reference has much more information about XML comments, including guidelines for how to document types and how to use the standard set of tags. Look for the "XML documentation" index entry.