Suppose we need to generate documentation for a .net project in the Microsoft HTML Help style, more known as .chm files. Different tools can be used depending on what it is being documenting.
We can use xml documentation by placing comments inside xml tags (like <summary> or <remarks>) within any line beginning with three space bars
The C# compiler processes documentation comments within the code to an XML file. This is done in the build process if the documentation xml file was specified in the project's build properties. (Notice that a lot of warnings about documentation will prompt if warning level is set to 4 in the project properties.)
Now, once we have the xml file, we want to parse it in order to generate easy reading documentation. Luckily, there is a free tool that does that: NDoc. Ndoc provides several output formats, including the MSDN one.
Including custom content in the chm file
If we need to include custom content in the chm file, other than the code documentation generated by NDoc, we have to write it in HTML format and then compile it into the chm file. The HTML Help SDK can be used for the last purpose. The SDK shipps with a tool, the HTML Help Workshop (
An HTML Help project consists of three parts:
- The Project itself (.hhp file)
- The Table of Contents (.hhc file)
- The Index (.hhk file)
Documenting XML schemas
It seems that the documentation of xml schemas is a little more complicated task. First we need to place comments inside the schema and then we need to generate the HTML help from them.
In order to place documentation inside an xml schema, the annotation component can be used..
But again, a way for generating the HTML Help from the documented schema is needed. This time I have found no free tool to do that. I have found a nice tool, Document!X, neither free nor open source. So, I decided to generate the MSDN documentation myself by transforming the xsd file into an HTML help file through a style sheet. The generated HTML file is later included in the chm file as any else custom content.