Generate .NET XML Documentation With NDoc

Systems documentation is one of those tasks that often suffers during the completion of a project. It's frequently pushed to the end of the development cycle, if it appears at all, in order to minimize redundant work.

However, with XML Documentation support in C# and VB.NET, and the development of NDoc, there is absolutely no reason we cannot document our systems in a much better fashion than we might have in the past. The work no longer lies in generating the documentation files; just in the documenting process itself.

My aim here is to show you how to install NDoc, and to run through a demonstration of how to use it. This article will not teach you how to document your code. Rather, it explains how to get your documentation into a useable form anyone can use.

NDoc Installation

There are a few different installation scenarios for NDoc, depending upon whether you use Microsoft Visual Studio.NET. Most of the existing documentation assumes you use Visual Studio, however, as many people don't, I'll provide the installation instructions for both Visual Studio and non-Visual Studio users here.

If you use Visual Studio.NET:

1. Verify you have the following directory: C:\Program Files\HTML Help Workshop


2. If you do not, you will have to download and install the HTML Help Workshop. Make sure you install it at C:\Program Files\HTML Help Workshop. You will find the code download at the HTML Help Workshop.


3. After ensuring the HTML Help Workshop is installed, download and install NDoc from NDoc Download. I recommend using the Web installer version, as it contains the latest stable release. If you decide not to use the Web installer, you will have to build the project in Visual Studio.NET. Once it's installed, you're ready to go.

If you don't use Visual Studio.NET:

1. Ensure you have the .NET Framework installed.


2. You must install the HTML Help Workshop at C:\Program Files\HTML Help Workshop. You will find the code download here:
   HTML Help Workshop


3. After correctly installing the HTML Help Workshop, download and install Ndoc from NDoc Download. I recommend using the Web installer version, as it contains the latest stable release. If you decide not to use the Web installer, please see the note below. Once NDoc is installed, you are ready to go.

Note: If you decide to install using the "most recent release" or the "stable release" without using the Web installer, and you DO NOT use Visual Studio.NET, you will have to download and install NAnt, a .NET build tool, available at NAnt download. Refer to the NDoc ReadMe.txt for more information.

Usage

Now that you've installed NDoc, let's use it to generate some documentation to ensure everything's working correctly. First, we will generate some basic code with XML Documentation tags. For a thorough treatment of the XML Documentation tags, refer to this page.

Here's the sample code, along with some comments:

// NDocSampleFile.cs
//

namespace NDocSample {
   using System;

  /**
       <summary>
           The NDocSample encapsulates some very rich functionality.
       </summary>
   */
   public class NDocSample {

       /**
           <summary>
               Default constructor for a new instance of NDocSample.
           </summary>
       */
       public NDocSample() {
       }
           /**
               <summary>
                   string someMethod(string string1, string string2, string string3)
                   Returns a string containing a concatenation of the values in string1
                   <param ref="string1" />, string2 <param ref="string2" />, and string3
                   <param ref="string3" />.
               </summary>
               <param name="string1">The first string.</param>
               <param name="string2">The second string.</param>
               <param name="string3">The third string.</param>
          */
           public static string someMethod(string string1, string string2, string string3) {
               // Perform some stuff here.
               return "somestuff";
           }
   }
}

This should be enough for us to test, make sure our installation was successful, and check that everything works.

NDoc needs both a compiled library, and the XML file generated when using XML Documentation, in order to process a build of the system documentation. So, we now have to compile the code and generate an XML Document. Since all we have here is one small file, I will simply compile this from the command-line. In order to generate the XML document, you have to use the /doc:filename.xml switch. Our command line syntax looks like this:

Dir>csc /debug /t:library /out:bin/NDocSample.dll NDocSample.cs /doc:NDocSample.xml

This will generate an NDocSample.dll in the bin directory, and NDocSample.xml in the root directory. As I mentioned, you'll need both these files in order to use NDoc.