Document .NET Libraries with XML Comments

Any development environment spawns standards. In the case of .NET, one of these standards is the way that developers expect class library documentation to look. Ideally, your class library documentation should follow the format and conventions that the .NET Framework SDK established for .NET namespaces.

Fortunately, this isn’t all that hard to do, at least if you’re working in C# (VB .NET will gain the same capabilities in Visual Studio 2005). A combination of the XML comments feature built into the language and the open source NDoc project makes it easy to generate high-quality SDK-style help. I’ll show you the basics in this article.

Adding XML Comments

The key to the whole process is the open source tool NDoc. NDoc is actually the end of a process that starts with Appendix B of the C# language specification: “C# provides a mechanism for programmers to document their code using a special comment syntax that contains XML text. In source code files, comments having a certain form can be used to direct a tool to produce XML from those comments and the source code elements, which they precede.” These comments are identified by being set off with three slashes instead of the two that normally introduce a C# comment.

The XML Documentation section of the C# Programmer’s Reference documents tthe XML tags that are used by these special commants.. Here are the XML documentation tags that Visual Studio .NET can use for XML documentation:

• <c>—Embedded code font in other text
• <code>—Multiple lines of source code
• <example>—An example of using a member
• <exception>—Specifies an exception that can be thrown by the current member
• <include>—Includes an external documentation file
• <list>—The heading row of a list
• <para>—A paragraph of text
• <param>—A method parameter
• <paramref>—A reference to a parameter in other text
• <permission>—The security permission required by a member
• <remarks>—Supplemental information
• <returns>—Return value of a method
• <see>—An embedded cross-reference to another member
• <seealso>—A reference in a See Also list
• <summary>—A summary of the object
• <value>—The value of a property

This list isn’t fixed by the C# specification; different tools are free to make use of other tags (and in fact NDoc understands a few tags that are not included on the standard list).

As an example, here’s some sample XML documentation embedded directly withing a C# library:

using System;

namespace XMLDoc
{
   /// <summary>
   /// This class contains static utility functions for use
   /// throughout the company.
   /// </summary>
   /// <remarks>
   ///      <para>As we develop general-purpose utility functions,
   ///            we will add them to this class.</para>
   ///      <para>The current utility functions include:</para>
   ///      <list type="bullet">
   ///         <item><see cref="FixQuotes" /> to fix up SQL
   ///               statements.</item>
   ///         <item><see cref="ReplaceNull" /> to convert nulls to
   ///               specified replacement valuess.</item>
   ///      </list>
   /// </remarks>
   public class Utility
   {
      /// <summary>
      ///      Static constructor
      /// </summary>
      static Utility()
      {
         // Nothing to do here
      }

      /// <summary>
      ///      Fix up a SQL statement by escaping single quotes
      /// </summary>
      /// <param name="SqlStatement" type="string">
      ///      <para>
      ///         A SQL statement, possibly with unescaped single quotes.
      ///      </para>
      /// </param>
      /// <returns>
      ///      Returns the SQL statement with any single quotes doubled.
      /// </returns>
      public static string FixQuotes(string SqlStatement)
      {
         return SqlStatement.Replace("'", "''");
      }

You get the idea, I’m sure. The XML comments contain all of the information that you’d like to see in a help file, and the tags provide all the information that’s needed for the right tool to structure that file.

From Comments to Documentation

Embedded in your code, these comments don’t do a lot of good for your customers. But Visual Studio .NET can collect these comments into an external XML file. To enable this collection, right-click on the project in Solution Explorer and select Properties. Then select the Build page and enter a name for the XML documentation file. By default, this file will be placed in the same folder as the compiled application.

After you’ve built the XML comments file for your application, NDoc can do its work. Figure 1 shows the NDoc user interface.

You can select one or more assemblies to document, and tell NDoc where to find the XML comments file for each assembly. NDoc will combine the information in the XML comments file with information determined by examining the assembly itself, and build MSDN-style documentation for you. Figure 2 shows a part of the resulting help file.

This little example shows both the ease of use and simplicity of NDoc, but there’s more power working there if you need it. NDoc has implemented a concept of pluggable documenters, so you can use the same XML comments to get out LaTEX markup, HTML Help, and other formats in addition to the MSDN standard. And, of course, it’s open-source so you could even add more functionality if you need it.

With these simple tools at your disposal, there’s no reason to put out a .NET class library for consumption by other developers without it having professional-looking documentation. These days, the successful developers are the ones who are willing to do more than just write code. Coming up with documentation is often an essential part of the job as well.

About the Author

Mike Gunderloy is the author of over 20 books and numerous articles on development topics, and the lead developer for Larkware. Check out his latest book, Coder to Developer from Sybex. When he’s not writing code, Mike putters in the garden on his farm in eastern Washington state.