代码改变世界

How To: Generate Source Code Documentation from XML Comments Using Microsoft SandCastle

2011-01-15 18:35  craystall  阅读(476)  评论(0)    收藏  举报

How To: Generate Source Code Documentation from XML Comments Using Microsoft SandCastle

 Microsoft has supported an application called SandCastle to help developer generate code documentation in formats like HTML and CHM.

To use SandCastle for generating code documentation you have to install several prerequisites:

To generate the documentation file, open SandCastle Help File Builder UI which by default located at C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderGUI.exe

clip_image002

The Help Builder will display the project properties. Use this screen to configure many things before generating the documentation file.

Html File Format

SandCastle allows you to generate different kinds of documentation file by configuring the HtmlFileFormat Property in the project properties screen.

clip_image004

The available HelpFileFormat are:

  • HtmlHelp1 which lets you to compile or generate the documentation in CHM file format. Html Help Workshop must be installed before generating the CHM file.
  • MSHelp2 which lets you to compile or generate the documentation into an HxC file format. To use this format, Microsoft Help 2.0 must be installed first. Microsoft Help 2.0 usually comes with VS2008 SDK but you can download it separately from http://www.x-tensive.com/Downloads/?Path=Freeware. Extract the SDK to C:\Program Files\ and run install.bat andinstall.reg to install Microsoft Help to your machine. The HxC documentation file can be opened using H2Viewer which can be downloaded at http://helpware.net/mshelp2/h2viewer.htm
  • HtmlHelpViewer which allows the Help Builder to generate documentation in MSHA format. You have to install Microsoft Help Viewer 1.0 which is shipped with VS2010 in order to use the generated documentation.
  • Website which allows the Help Builder to generate the documentation in Html files so the documentation can be opened with web browser

General Property

There are several properties that is usually use in the Help Builder project besides setting up the HtmlFileFormat property

clip_image006

HelpTitle: set help title

HtmlHelpName: set the documentation name (e.g.: filename.CHM, filename.HxC)

clip_image008

OutputPath: set the folder to which the generated documentation is placed

Generating the Documentation File

These are the steps to generate the Documentation file:

1. Choose HtmlFileFormat. This example will use HtmlHelp1

2. Set documentation name, output path, and documentation filename. This example will use the GenaralUtility project from my previous post Using XML Comments to Document Source Code so set the HelpTitle property to General Utility, HtmlHelpName toGeneralUtility, and set the OutputPath to the desired location

3. Add the Documentation Source by right clicking the “Documentation Sources” node in the Project Explorer Panel in the right side and choose “Add Documentation Source”. Navigate to the General Utility project folder and add GeneralUtility.dll as the documentation source.

clip_image010

clip_image012

clip_image014

4. Build the documentation by clicking the Build help file button. A build output screen will appear and display the build process and status. Wait until the build finish.

clip_image016

clip_image018

clip_image020

After the build process finish, go to the output folder and you can see that there is a CHM file called GeneralUtility.CHM. This is the documentation file generated by SandCastle Help Builder. The texts or data in the CHM file is generated from the XML Comments that you have entered in the code.

clip_image022

clip_image024

You can also generate different kinds of documentation file besides the CHM file by setting up the HelpFileFormat property in the help project properties.

Summary

I have explained about the XML Comments and tags used in the XML Comments in my previous post Using XML Comments to Document Source Code. I’ll retype the usage of the tags and the source code of General Utility Class here

XML Comments tags:

  • <summary> tag: used to describe the member being documented. The text in the <summary> tag is the only source of information about the member in the IntelliSense and in Object Browser
  • <para> tag: The <para> tag is for use inside a tag, such as <summary>, <remarks>, or <returns>, and lets you add structure to the text.
  • <c> tag: The <c> tag gives you a way to indicate that text within a description should be marked as code. Use <code> to indicate multiple lines as code.
  • <code> tag: The <code> tag gives you a way to indicate multiple lines as code
  • <example> tag: The <example> tag lets you specify an example of how to use a method or other library member. You can also add source code here with <code> tag
  • <exception> tag: The <exception> tag lets you specify which exceptions can be thrown. This tag can be applied to definitions for methods, properties, events, and indexers.
  • <list> tag: create a list definition in the XML comments
  • <returns> tag: The <returns> tag should be used in the comment for a method declaration to describe the return value
  • <remarks> tag: The <remarks> tag is used to add additional information about the member, supplementing the information specified with <summary>. This information is displayed in the Object Browser
  • <param> tag: The <param> tag should be used in the comment for a method declaration to describe one of the parameters for the method. To document multiple parameters, use multiple <param> tags. The text for the <param> tag will be displayed in IntelliSense, the Object Browser, and in the Code Comment Web Report.
  • <see> tag: The <see> tag lets you specify a link from within text

The Utility class source code:

/// <summary>
/// A General utility class containing several methods that will help you code easier
/// <para>Utility version 4.5</para>
/// <para>Developed by : Coding Hero</para>
/// </summary>
public class Utility
{
    /// <summary>
    /// Initializes a new instance of the <see cref="Utility">Utility</see> class.
    /// </summary>
    public Utility()
    {
 
    }
 
    /// <summary>
    /// <c>GetFullName</c> is a dummy method to get the full name.
    /// <para>Well, you can simply concat the string actually.</para>
    /// <para>No need to use this method, it's an example anyway.</para>
    /// </summary>
    /// <remarks>
    ///        <para>As we develop general-purpose utility functions, we'll constantly changes the function so be prepared.</para>
    ///        <list type="bullet">
    ///        We'll support adding <see cref="int"></see> paramater type
    ///        We'll support adding <see cref="double"></see> paramater type
    ///        We'll support adding <see cref="bool"></see> paramater type
    ///        We'll support adding <see cref="decimal"></see> paramater type
    ///        </list>
    /// </remarks>
    /// <example>Example to use:
    ///     <code>
    ///     string firstname = "Michael";
    ///     string lastname = "Jordan";
    ///     string fullname = GetFullName(firstname,lastname);
    ///     </code>
    /// </example>
    /// <param name="firstName">The first name.</param>
    /// <param name="lastName">The last name.</param>
    /// <returns><see cref="string">string</see>: full name</returns>
    /// <exception cref="InvalidOperationException">Thrown Invalid Operation Exception when you throw them from the code</exception>
    public string GetFullName(string firstName, string lastName)
    {
        return firstName + " " + lastName;
    }
 
    /// <summary>
    /// This is also a dummy method to remove string from another string.
    /// </summary>
    /// <remarks>This method is an optional method if you don't want to use string.Replace</remarks>
    /// <example><para>Example of the code</para>
    ///     <code>
    ///         string str = "Asimilation";
    ///         string result = RemoveString(str,"on")
    ///     </code>
    /// </example>
    /// <param name="str">The STR.</param>
    /// <param name="strToRemove">The STR to remove.</param>
    /// <returns><see cref="string">string</see>: processed string</returns>
    public string RemoveString(string str, string strToRemove)
    {
        return str.Replace(strToRemove, string.Empty);
    }
}

To get more understanding about the XML Comments and what information we should put in the tags, I’ll explain the correlation of texts in the XML Comments tag and the generated documentation file. The picture below explains the correlation.

The Utility Class

clip_image026

The GetFullName method

clip_image028

clip_image030

SandCastle Help Builder can help you generate code documentation in just minutes. It can produce different kinds of file format and very easy to use.

The documentation is generated from texts entered within tags in XML Comments in the code, so remember to put good information on the XML Comments you entered in the code.

Hope this post helps.