Create html and chm documentation from C# or C++ Visual Studio source code

Products to be used

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.

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.

Procedure for generating the technical documentation

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”.

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.

C# and C++ comments restrictions in Visual Studio ®

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® and Html Help Workshop® are registered trademarks of Microsoft.

Leave a Reply