By: Chris Cyvas

February 21st, 2004

Reader Rating: 9.5

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 [1].


3. After ensuring the HTML Help Workshop is installed, download and install NDoc from NDoc Download [2]. 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]


3. After correctly installing the HTML Help Workshop, download and install Ndoc from NDoc Download [4]. 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 [5]. 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 [6].

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.

NDoc in Action

Now that we have those two files, we can fire up NDoc. You can use NDoc from the command line; however, in order to illustrate the features of NDoc, we will use the GUI in this case.

In order to get your documentation, click on the "Add" button. This brings up the "Add Assembly Filename and XML Documentation Filename" dialog. Click on each ellipses button, navigating to the bin directory to select the NDocSample.dll, and to the root directory to select the NDocSample.xml files, respectively.

Once you click "OK", NDocSample.dll will be listed under the header "Selected Assemblies to Document".

Moving on, we can now look at the "Select and Configure Documenter" section, which is where most of your work will occur. Under the Documentation Type, you are given the option of creating documentation in the following types: MSDN, JavaDoc, XML, LaTeX (Alpha), Linear HTML (Alpha). I'll choose MSDN, as this is a widely accepted format for my work environment. For information on the other options, refer to the NDoc Website [7].

For the rest of the "Select and Configure Documenter" section, you can choose a series of properties that you may or may not wish to assign. Of special note are OutputDirectory and OutputTarget. You should set the OutputDirectory to the "docs" directory, which should be created under the root of the project. When you select OutputTarget, you're given three choices:

1. HtmlHelp - generates a .chm file, as well as the supporting html files


2. Web - generates a series of html files, index.html being the starting file


3. HtmlHelpAndWeb – generate both sets of documentation listed above

Simply click the "Build" button or Ctrl+Shift+B. You can watch the bottom of the NDocGui for feedback about what's going on. When it's complete, you will see "Ready" in the lower left corner.

Now, go into your docs directory to see the files that were generated. As I opted for the HtmlHelp version, I will locate the .chm file and fire it up.

Professional systems documentation in a matter of seconds!

Conclusions

You're now ready to try documenting some existing projects. I will leave all the properties for you to investigate, as there are several, and providing a treatment for each is well beyond the scope of this article.

Systems documentation has never been so easy! This is one of those tools that will go a long way in providing professional solutions for your clients, as well as other in-house developers.

Happy documenting!

[1] http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
[2] http://ndoc.sourceforge.net/download.html
[3] http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
[4] /ndoc.sourceforge.net/download.html
[5] http://nant.sourceforge.net
[6] http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vcorixmldocumentation.asp
[7] http://NDoc.sourceforge.net