Login | Register   
RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Producing Professional MSDN-style Documentation with .NET and NDoc


he .NET framework provides a nice way to insert XML documentation tags inside C# source code. These tags can then be extracted to an XML file, and using NDoc, transformed into fully-functional MSDN-style documentation.

Software Needed
Before delving into the how the process works, here's a short list of the software you need to run the samples for this article:

Author's Note: If you have installed Visual Studio .NET you might already have the HTML Help Workshop installed on your machine. You can verify that by checking for the directory C:\Program Files\HTML Help Workshop.

Installing NDoc is generally very smooth, so it doesn't require any additional instructions.

Figure 1. MSDN-style documentation sample: This is the quality of documentation that you can get directly from the C# XML comments with NDoc.
If you don't have Visual Studio .NET, don't worry, at the end of this article I'll describe how you can still use NDoc, provided that, of course, you have at least the .NET framework installed plus HTML Help Workshop and NDoc.

XML documentation tags in C#
The process of building MSDN-style documentation similar to Figure 1 can be summarized in three main steps:

  • Document your C# source code by using the XML documentation tags.
  • Extract the XML documentation tags to an XML file.
  • Tell NDoc where it can find the extracted XML file and the assembly associated with it—that is the .dll or .exe file.
Typically, you'll use a rather short list of XML tags to document your C# source. The following table lists the most-used tags (in alphabetical order) with a short explanation and an example for each one:

Table 1: The table shows an alphabetical list of the most commonly used XML tags when documenting C# source code.
Tag Description Example
<c> Used to differentiate the code font from the normal text font.

The <c>Foo</c> class provides...

<code> Similar to <c> but used to demarcate multiple lines of code. Usually used to show a code usage example.

// create an instance of the Foo class
  Foo f = new Foo();
  // call the Bar()method

<example> Used to illustrate a code usage example. This tag is generally used in concert with the <c> and/or the <code> tag.

The following code illustrates a possible use of
   the <c>Foo</c> class:
     // create an instance of the Foo class
     Foo f = new Foo();
     // call the Bar() method

<exception> Used to indicate the exceptions that the current member can throw.

<exception cref="ArgumentNullException">
   if <paramref name="myParam" /> is <c>null</c>

<para> Used to control the format of the documentation output

The <c>Foo</c> class...

<param> Describes a method parameter.

<param name="myFoo">
   A <see cref="Foo" /> type representing…

<paramref> Used to refer to a parameter previously described with the <param> tag.

If <paramref name="myFoo" /> is <c>null</c>
the method will...

<remarks> Used to supply further information about the member it describes.

   <para> The <c>Foo</c> type is thread-safe... </para>

<returns> Describes the return value of a method.

The length of <paramref name="someString" />

<see> Used to create a cross-reference to another member (included .NET types, for example, the System.String type).

The <see cref="System.String" /> <paramref
name="someString" /> represents...

<summary> Used to provide the summary of the member it precedes.

This class is used as a bridge between...

Comment and Contribute





