Developer.com content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.
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.
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.
