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.



Comments

  • 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

    Reply
  • 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=http://www.prozacbuyonline.com/#17-order-prozac-online-without-rx-cheap]purchase generic Prozac Fluoxetine online[/url] We do not share your e-mail address

    Reply
  • Order Cheap Zyprexa Online Cheap

    Posted by Stefani822 on 07/04/2013 08:46am

    http://zyprexabuyonline.com/#purchase-zyprexa-drug-cheap-85 Zyprexa Online No Rx - zyprexa vs prozac

    Reply
  • 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

    Reply
  • 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=http://www.lexaprobuyonlinepills.com#lexapro-without-rx]online lexapro[/url] 2005 buying lexapro online- Buy Escitalopram Medication, lexapro purchase. lexapro effect on libido. Understanding Depression Slideshow will generic version lexapro available

    Reply
  • 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

    Reply
  • valtrex 500 mg generic

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

    did valtrex become generic valacyclovir online sales [url=http://flavors.me/propgan#purchase-valtrex-cheap]purchase valtrex online no prescription[/url] valacyclovir to buy [url=http://s3tv1g.pen.io/#buy-valtrex-in-australia]what is the generic form of valtrex[/url] where to purchase valtrex [url=http://flavors.me/disfbil#buy-generic-valacyclovir-online]what is the generic name of valtrex[/url] buy cheap valtrex usa [url=http://v8q8ec.pen.io/#valacyclovir-generic-canada]generic valtrex canadian pharmacy[/url] cost of valacyclovir vs acyclovir [url=http://m4skos.pen.io/#buy-valtrex-cheap]is valacyclovir generic for valtrex[/url] where can buy valtrex valacyclovir hcl generic

    Reply
  • 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

    Reply
  • 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=http://wrhiw8.pen.io/#best-place-to-buy-roaccutane-online]buy 40 mg accutane[/url] safest place buy accutane [url=http://flavors.me/caetea#accutane-isotretinoina]what is the best facial moisturizer to use while on accutane[/url] can you still buy accutane [url=http://yk4gyw.pen.io/#buy-accutane-online-canada-pharmacy]where can i buy accutane cream[/url] how long do i have to take accutane for [url=http://flavors.me/creeptai#buy-accutane-south-africa]how much does accutane cost a month[/url] can i take diet pills while on accutane [url=http://1aocuk.pen.io/#cost-of-accutane-generic]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

    Reply
  • order flagyl cheap

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

    buy flagyl in uk flagyl 400mg what is it for [url=http://flavors.me/tailar#generic-forms-of-flagyl]how much does flagyl 500 mg cost[/url] get flagyl online [url=http://ancf5x.pen.io/#flagyl-400-generico]buy flagyl oral[/url] buy flagyl er 750 mg [url=http://ylvhym.pen.io/#how-to-order-flagyl]buy generic flagyl online[/url] where can i buy flagyl metronidazole [url=http://319gnn.pen.io/#need-order-flagyl]flagyl 500 mg price[/url] generic brand for flagyl [url=http://flavors.me/ocches#flagyl-buy-online]generico flagyl 400mg[/url] prescription flagyl used flagyl comp orales 250 mg

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

Top White Papers and Webcasts

  • Live Event Date: December 11, 2014 @ 1:00 p.m. ET / 10:00 a.m. PT Market pressures to move more quickly and develop innovative applications are forcing organizations to rethink how they develop and release applications. The combination of public clouds and physical back-end infrastructures are a means to get applications out faster. However, these hybrid solutions complicate DevOps adoption, with application delivery pipelines that span across complex hybrid cloud and non-cloud environments. Check out this …

  • Relying on outside companies to manage your network and server environments for your business and applications to meet the needs and demands of your users can be stressful. This is especially true as many Managed Hosting organizations fail to meet their service level agreements. Read this Forrester total economic impact report and learn what makes INetU different and how they exceed their customers' managed hosting expectations.

Most Popular Programming Stories

More for Developers

RSS Feeds