Generation Documentation for a .Net Project
This post was originally published at http://solepano.blogspot.com
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.
Documenting code
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.
http://www.mshelpwiki.com/index.php?
http://www.microsoft.com/downloads/details.aspx?familyid=ce1b26dc-d6af-42a1-a9a4-88c4eb456d87&displaylang=en