Introduction
Working on a project of any size, we all know how important good documentation is. Getting to write it is another issue though.
C# and the Microsoft .NET Framework has taken measures to help you with that. An XML documenting standard has been introduced that you write directly into the source code; much like Javadoc for Java.
In this article, I will explain how to document using the XML tags, how to use NDoc to convert the XML into very nice looking HTML Help files, and last but not least, how to integrate the help into Visual Studio .NET.
Prerequisites
Before you can start documenting, you will need a couple of programs that are all available as free downloads:
I am not going to explain how to install these programs, they pretty much all install completely automatic. After installing all of those, you should be ready to start creating nifty documentation, that will be available directly in Visual Studio as Dynamic Help and Intellisense.
The actual commenting
The actual commenting of your source code is explained in this excellent article: C# Documenting and Commenting.
When you generate the NDoc documentation, you need to use the HtmlHelp2 format.
Using H2Reg to integrate the documentation into VS.NET
Usually, you would have to install a help file using a .msi install script. In this case, that is just way too much work. Fortunately, Helpware has made a small utility called H2Reg that can do it for us. It requires a configuration file and must be called from the command-line, so I thought a little helper program could make it a bit easier. There is a download link at the top of this article.
All you need to do now is fill in the fields and press Generate. The program will make a directory called Help in your project directory that will contain the configuration file, and two batch files that you can use to register and unregister the help files in Visual Studio .NET:
The help collection file you can find in the ./doc directory in your project directory (if you did not change the default NDoc directory, that is).
The program will generate the files in a directory called Help, one level above the NDoc directory. After you generate the files, you just need to run the register.bat batch file to register your help in Visual Studio .NET.
If you have problems with the collection not being registered, have a look at H2Reg's log file called C:\Program Files\Helpware\H2Reg\H2Reg_Log.txt (assuming you installed it in the default directory).
Including the help into Visual Studio .NET
The help files have now been activated and integrated into the Visual Studio Help Collection. You might need to restart Visual Studio .NET if you have it running.
Now we have context sensitive help, Intellisense and dynamic help:
Conclusion
In a few simple steps, we have integrated help for our own code, pretty much all over the place.
To me, this is really a productivity booster. What about you?
Revision History
- January 18th, 2004: Updated with new program and instructions to use HtmlHelp2.
- January 22nd, 2004: Updated program to auto-register into Visual Studio's Help Collections, and updated article to reflect it.
