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