email article printer friendly more resources

Write Better C# Documents
The C# compiler produces XML documentation files from your comments. NDoc, an open source tool, takes that output and produces a Windows help file for your class libraries.
by Bill Wagner

October 2003 Issue

Technology Toolbox: C#

If you're like most developers, you probably think you can never have too many tools, especially ones that you can download for free. NDoc is such a tool, and can really help in your C# development. It builds a compiled help file from the XML files that the C# compiler generates from your source documents. It's a great, automated way to build programmer documentation automatically for your class libraries.

I reviewed the latest stable version, from October 29, 2002. Although the 1.1 version doesn't work with VS.NET 2003, the 2.0 release does. All the features described work in both versions. However, if you find bugs in this version, you can download the latest nightly build from the NDoc Web site. Once you download NDoc, simply build and install it, and you're ready to go. NDoc has two different executables: a console version, and a GUI version. I'll compile a help file for my clipboard application to walk you through NDoc's typical usage.

NDoc reads the VS.NET Solution file to determine where the XML documentation for your project is located. You need to set the XML Documentation File setting in your project (see Figure 1). Don't leave this blank; if you do and build your comment Web pages using the Tools:Build Comment Web Pages command, NDoc can't find them.

Now, start the NDoc GUI program (see Figure 2). Select "New from Visual Studio Solution" from the Project menu item. Navigate to your solution and select it. NDoc displays all the assemblies in the solution for you. (This is where I found the first bug: NDoc can't load a solution that includes a deployment project.) One way to work around this is to create a project and add assemblies to it.

To finish, select the build icon from the toolbar. It's easy to find; it looks suspiciously like the VC6 build icon. NDoc creates a help file using styles that match the MSDN documentation for Visual Studio .NET.

Finally, I wanted to add NDoc to the Tools menu in VS.NET. That way, I could build the help file for an existing NDoc project automatically. Unfortunately, there wasn't an easy way to select the project inside VS.NET. (This is a VS.NET limitation, not an NDoc limitation.)

There are a few more features worth mentioning in NDoc. You can change the documentation stylesheets to display in the style of MSDN, JavaDoc, or straight XML. The XML style produces a simple XML file with some of the NDoc error checking mentioned below.

Another nice feature in NDoc is that it can help find omissions in your comment-generated documentation. The flags that show missing values generate error statements in the help file if any of the necessary fields (such as summary and remarks) are missing in your generated documentation. NDoc even loads the assembly and uses reflection to see if there are methods or properties you haven't documented at all (see Figure 3).

All in all, NDoc is a worthwhile addition to your tool chest. Hopefully, it'll save valuable time when you need to generate documentation for your class library projects.