Generating Documentation for .NET Project

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

. For a complete tag reference see TagsForDocumentationComments .

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 (\hhw.exe), that is used to create HTML Help Projects.

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.

Links:

http://www.mshelpwiki.com/index.php?
http://www.microsoft.com/downloads/details.aspx?familyid=ce1b26dc-d6af-42a1-a9a4-88c4eb456d87&displaylang=en

Blog's Birth

My blog has born at last!

What is this blog about? This is a developer's blog, so just technical issues will be posted. The idea is to use this blog as a sort of knowlage base, just to write the daily little research and findings, for others to read and for me to remember. I was definitely needing a place to store all my writings and links and stuff, so I am very happy for this beginning and hope to keep it updated.

Of course averyone is welcome to contribute by posting comments or contact me.