Click here to Skip to main content
15,867,834 members
Articles / Web Development / ASP.NET
Article

Documentation of .NET Class Libraries using NDoc

Rate me:
Please Sign up or sign in to vote.
2.60/5 (2 votes)
6 Jan 2008CPOL4 min read 45.2K   19   6
This article explains how to use NDoc for documenting .NET class libraries.

Introduction

API documentation of an application is one of the most tedious tasks for all developers. NDoc makes it very easy for everyone. 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 are unfamiliar with this license or have questions about it, here is a FAQ.

Using the Code

You can download the NDoc utility files from SourceForge.Net. Now open the solution for which you want to generate documentation in Visual Studio 2005. Add a sample class library to test or you can use any existing one. Select the class library for which you want to create documentation. Right click on it and click on “Properties”. You will see the following dialog box.

Property Screen

Now click on the ‘Build’ tag.

Build Config Screen

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

Now build your class library. Just check the Debug/Release folder (depends on your build configuration). You will see the documentation file in XML format. NDoc’s help will give you a 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 an 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:

    C#
    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:

    C#
    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. Moreover, 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 manually.

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

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. The same folder contains the command line utility NDocConsole.exe. We can use the command line utility for the automated build process. In this article, I am going to explain the GUI utility only. Double click on NDocGui.exe. You will see the NDoc GUI console.

NDoc GUI Screen

Click on Project->New. Notice the “Select and Configure Documenter” section. Here you can specify the output documentation type. NDoc can generate a document in various formats 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 the visibility section. Just check which elements you want to document. For example, private variables, protected variables, Namespaces without summaries etc. (Check out the red eclipse in the following image.)

visibility option

Now click on Add.
This will open up the following dialog box.

add assembly

You will see a small command button to specify a value for the 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 an XML documentation file as per the selected EXE or DLL file.
Now save the NDoc project file somewhere. So next time if we modify the source, we can open the saved project in NDoc and then we can do the documentation build again.
Now Build the file. You can see the Build button on the left upper corner of the screen shown below. Click on it.

Build Button

All build messages will appear in the “Output” section of the GUI console. You will see the last message as given below:

plain
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 the output message. You will find the *.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!

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


Written By
Software Developer Covelix Technologies, Pune, India.
India India
5+ years of technical experience.

Completed graduation from Govt. Engineering college, Pune.
Working as SW developer in Covelix for more than 3 years.

My technical experience includes n-tier applications in .NET, MFC | C, C++, C#, Python | SQL server, Oracle 10g | AJAX | Installsheld.

Comments and Discussions

 
GeneralAlternative Pin
Barry Jones27-Jul-10 0:59
Barry Jones27-Jul-10 0:59 
Generalvisual studio 2008 Pin
musabyildiz8-Mar-10 21:22
musabyildiz8-Mar-10 21:22 
QuestionNDoc syntax highlighting for CODE block (tag) Pin
Aoi Karasu 15-Nov-09 23:54
professional Aoi Karasu 15-Nov-09 23:54 
GeneralAble to generate the Documentaion using Ndoc Pin
sathishkumar_rs12-Feb-09 23:26
sathishkumar_rs12-Feb-09 23:26 
GeneralNice try, but the NDoc project is dead... Pin
Juergen Posny7-Jan-08 3:28
Juergen Posny7-Jan-08 3:28 
Hi,

Your article is a nice read for a beginner, but you should change it a little bit.
First of all, the NDoc project is not supported or updated anymore on sourceforge you can see the last version (1.3.1) is from 2005 and targets Net 1.1 .
If you try more commenting with NDoc 1.3.1 you'll see, generics and other Net 2.0 features are not processed correctly.

For commenting Net 2.0, you should use Sandcastle, NOT NDoc anymore.
Search on www.codeplex.com for "Sandcastle" and you'll find some good tools.
(Sandcastle-Helpfile-Builder is a tool having nearly the same GUI as NDoc).

I used NDoc for years, but now, it's not usefull anymore...

Greetings, Juergen
GeneralRe: Nice try, but the NDoc project is dead... Pin
Fernando A. Gomez F.7-Jan-08 7:16
Fernando A. Gomez F.7-Jan-08 7:16 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.