Create html and chm doc...

Create html and chm documentation from C# or C++ VS 2005/2008 source code

This article explains how to generate html and chm files from a project written in C# or C++ under Visual Studio 2005 & 2008 ®.

Summary

Products to be used.
Procedure for generating the technical documentation.
C# and C++ comments restrictions in Visual Studio 2005 & 2008 ®.

1. Products to be used

1.1 Doxygen

Doxygen (doxywizard.exe) is used to generate HTML documentation from source files. Furthermore, it generates the elements needed to create the .chm (compressed HTML) file too. Doxygen can be used under the terms of the GNU General Public License. Doxygen can be downloaded from www.doxygen.org.

1.2 Microsoft HTML Help Workshop ®

HTML Help Workshop (hhw.exe) is used to generate compressed HTML files (.chm). This tool is free and can be downloaded from here.

2. Procedure for generating the technical documentation

2.1 Generating HTML files

Execute Doxygen GUI frontend (doxywizard.exe).
Configure the parameters by using either "Wizard" or "Expert" mode.
In order to prepare the .chm file generating, in "Output" tab, it has to check "HTML" and "prepare for compressed HTML" in wizard mode. Whether the expert mode has been chosen, in "HTML" tab, it has to check "GENERATE_HTMLHELP" and to enter the .chm filename (with the extension) in "CHM_FILE" field.
Save the configuration file.
Run the generating process by clicking on the "Start" button.
Check the result by executing "index.html" in the "html" sub folder.

In addition of the html documentation, three more files are supposed to be generated in the "html" sub folder: "index.hhp", "index.hhc" and "index.hhk".

2.2. Generating compressed HTML file (.chm)

Execute HTML Help Workshop (hhw.exe).
Open the project file: index.hhp.
Eventually change the compiled file location to drop it in the "Doc" folder.
Compile the HTML files.
Outside HTLM Help Workshop, open the created file in order to check it.

3. C# and C++ comments restrictions in Visual Studio 2005 & 2008 ®

Doxygen recognize the C# and C++ comments tags like ///<summary></summary>, ///<param></param>, ///<returns></returns> and the other ones. But, for example, under Windows version, it does not recognize the line feed in comments.

So, whether you want to go beyond these basic features and if you want to format your comments, the best way is to use the Doxygen tags inside the standard comments tags (refer to Doxygen documentation for details).

The Visual Studio compiler does not send any warning about these, but, unfortunetly, these tags appear in the tooltips in the editor.

Below is a sample with "\n" tag for the line feed and, "\code" and "\endcode" to show the encapsulated text like code pattern in the output help file.

        /// <summary>
        /// Load a config XML file.
        /// \n\n XML file format:
        /// \code
        /// <Parent>
        ///     <Child Name='ID' Type='Type1' />
        ///     ...
        /// </Parent>
        /// \endcode
        /// </summary>

Visual Studio 2005®, Visual Studio 2008® and Html Help Workshop® are registered trademarks of Microsoft.