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.


  • Zyprexa Without Rx

    Posted by zyprexa-online-buy on 07/07/2013 06:22am

    zyprexa und seroquel, More Help: Buy Olanzapine Without Prescription Cheap - zyprexa lawsuit 2009, Buy Cheap Zyprexa

  • purchase Fluoxetine online no prescription

    Posted by BuyProzac5 on 07/04/2013 08:15pm

    Find out how depression disturbs sleep and get some effective tips to help your sleep problems. buy Prozac 60mg online purchase Prozac 40mg online A 2008 meta-analysis based on 32 trials found a robust effect of this method on depression, and it appeared similarly effective for both uncomplicated depression and depression that is resistant to medication. [url=]purchase generic Prozac Fluoxetine online[/url] We do not share your e-mail address

  • Order Cheap Zyprexa Online Cheap

    Posted by Stefani822 on 07/04/2013 08:46am Zyprexa Online No Rx - zyprexa vs prozac

  • Order Cheap Olanzapine Online Medication

    Posted by Kristen946 on 07/02/2013 12:34pm

    Order Cheap Zyprexa Online Order Olanzapine No Prescription Cheap - zyprexa side effects fatigue

  • order generic Lexapro Escitalopram online

    Posted by Traistasteway on 06/30/2013 11:23pm

    Anxiety is the most common mental illness in America as approximately 40 million adults are affected by it. Learn more about suicide, including who is at risk, warning signs, and when to call for medical assistance. lexapro 25mg side effects. In addition, behavioral activation appears to take less time and lead to longer lasting change. lexapro and pregnancy. Buy Escitalopram Online Without a Prescription Cheap, Web Site- [url=]online lexapro[/url] 2005 buying lexapro online- Buy Escitalopram Medication, lexapro purchase. lexapro effect on libido. Understanding Depression Slideshow will generic version lexapro available

  • order Escitalopram online without a prescription

    Posted by IndemiEffeddy on 06/29/2013 11:36am

    Order Escitalopram Online Without Prescription Lexapro Online Without Prescription Cheap - Order Cheap Generic Lexapro

  • valtrex 500 mg generic

    Posted by Mastifopul on 06/28/2013 09:13am

    did valtrex become generic valacyclovir online sales [url=]purchase valtrex online no prescription[/url] valacyclovir to buy [url=]what is the generic form of valtrex[/url] where to purchase valtrex [url=]what is the generic name of valtrex[/url] buy cheap valtrex usa [url=]generic valtrex canadian pharmacy[/url] cost of valacyclovir vs acyclovir [url=]is valacyclovir generic for valtrex[/url] where can buy valtrex valacyclovir hcl generic

  • Purchase Prozac Generic Cheap

    Posted by Polina568 on 06/28/2013 03:55am

    Order Prozac at Discounted Price Purchase Prozac Online Without Prescription - effexor vs prozac hot flashes

  • buy generic accutane

    Posted by Flapinjasu on 06/27/2013 11:16pm

    how long does it take accutane to clear up acne can you really buy accutane online [url=]buy 40 mg accutane[/url] safest place buy accutane [url=]what is the best facial moisturizer to use while on accutane[/url] can you still buy accutane [url=]where can i buy accutane cream[/url] how long do i have to take accutane for [url=]how much does accutane cost a month[/url] can i take diet pills while on accutane [url=]why does accutane make your face worse before it gets better[/url] how severe does your acne have to be to get accutane can you do laser hair removal while on accutane

  • order flagyl cheap

    Posted by Niohosafa on 06/27/2013 09:07pm

    buy flagyl in uk flagyl 400mg what is it for [url=]how much does flagyl 500 mg cost[/url] get flagyl online [url=]buy flagyl oral[/url] buy flagyl er 750 mg [url=]buy generic flagyl online[/url] where can i buy flagyl metronidazole [url=]flagyl 500 mg price[/url] generic brand for flagyl [url=]generico flagyl 400mg[/url] prescription flagyl used flagyl comp orales 250 mg

Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • As all sorts of data becomes available for storage, analysis and retrieval - so called 'Big Data' - there are potentially huge benefits, but equally huge challenges...
  • The agile organization needs knowledge to act on, quickly and effectively. Though many organizations are clamouring for "Big Data", not nearly as many know what to do with it...
  • Cloud-based integration solutions can be confusing. Adding to the confusion are the multiple ways IT departments can deliver such integration...

Most Popular Programming Stories

More for Developers

RSS Feeds

Thanks for your registration, follow us on our social networks to keep up-to-date