Documentation of .NET class Libraries using NDoc

Introduction

API Documentation of application is one of the most tedious tasks for all developers. NDoc
makes it very easy for all. In this article I will try to explain how we can use NDoc
to generate MSDN style documentation for your class libraries.


Background
NDoc generates class libraries documentation from .NET
assemblies and the XML documentation files generated by the C# compiler (or an
add-on tool for VB.NET such as VBCommenter.

NDoc uses add-on documenters to generate documentation in several different
formats, including the MSDN-style HTML Help format (.chm), the Visual Studio
.NET Help format (HTML Help 2), and MSDN-online style web pages.

The NDoc source code is available under the GNU General Public
License. If you unfamiliar with this license or have questions about it,
here is FAQ


Using the code
You can download NDoc utility files from SourceForge.Net

Now open the solution for which you want to generate documentation for in Visual Studio 2005. Add sample class library to test or you can use any existing one.

Select the class library for which you want to create documentation for. Right click on it and click on “Properties”.

You can see following dialog box.















Now click on ‘Build’ tag.
















You will see one check box “XML documentation file:” (See red eclipse part above.)
Just enable that check box and specify name for doc file. NDoc uses this file for creating documentation.

Now build your class library. Just check Debug/Release folder (Depends on your build configuration). You will see the documentation file in XML format.

NDoc’s help will give you brief idea about how you can document your class library more effectively.

Here are some tips from NDoc’s documentation.

1. The more code comments you add to your code, the more descriptive the generated help topics will be.

2. At a minimum each public type, and the public and protected members of your public types, should have a

item describing what the member does or represents.

The VS.NET C# code editor has a handy feature that makes it easy to create the basic code comments for each type and member:

For the following code snippet:

public class MyClass() {

public MyClass( string s ) { }

}

if you place your cursor just above the MyClass constructor, and hit the '/' character three times in a row,
VS.NET will create the skeleton of a code comment block for that member:

public class MyClass() {
/// <summary>
///
/// </summary>
/// <param name="s"></param>
public MyClass( string s ) { }
}

This applies to any type or member that can have code comment tags associated with it. Further more,
once you have a code comment block, when you hit the '<' key to start a new tag, VS.NET will display an intellisense selector showing the appropriate list of code comment tags.
Unfortunately this list won't include the additional tags that NDoc supports, but you can still add them by hand.

NDoc supports large number of documentation tags. You can use it as per your need.

Ok… so your project is now ready for documentation.
Now just unzip the NDoc file which you have already downloaded from SourceForge.net. I have this version “ndoc-bin-1.3.1-v16.zip”.

Browse the unzipped archive and locate file NDocGui.exe. This gives a better GUI to use NDoc. Same folder contains command line utility “NDocConsole.exe”.
We can use command line utility for automated build process.

In this article I am going to explain about GUI utility only.

Double click on “NDocGui.exe”. You will see NDoc GUI console.
















Click on Project->New.

Notice “Select and Configure Documenter” section. Here you can specify output documentation type. NDoc can generate document in various format like MSDN, Linear HTML, JavaDoc etc.

Select MSDN for now.

Below that you can see various options to configure your documentation output like Copyright text, Output directory etc.

The most important settings are in visibility section. Just check which elements you want to document. For example, private variables, protected variables, Namespaces without summaries etc. (check red eclipse in following image.)
















Now click on Add.

This will open up following dialog box.








You will see small command button to specify value for key "Assembly", through which you can browse for your assembly path.

Select the “exe”/ “dll” file of your application, which you want to document.

NDoc will automatically take XML documentation file as per selected exe or dll file.

Now save the NDoc project file somewhere. So next time if we modify source, we can open saved project in NDoc and then can do the documentation build again.

Now Build the file. You can see the Build buttion on left upper corner of below screen. Click on it.














All build messages will appear in “Output” section of GUI console. You will see last message like,

Created c:\Documents and Settings\vinayakc\Desktop\New Folder\doc\ndoc_msdn_temp\Documentation.chm, 57,879 bytes

Compression decreased file by 238,719 bytes.

Html Help compile complete

Done.

Now check the output directory specified in output message. You will find “.chm” file there which will be the compiled documentation for your class library.
Just double click it and enjoy your application’s professional documentation.

Happy Coding!! :)