Development Matters Blog

Once you have finished documenting your code, you are ready for the Sandcastle. Sandcastle essentially is a documentation compiler. You can download it at:

http://www.microsoft.com/downloads/details.aspx?familyid=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en

It is a command prompt tool, but a number of open source GUIs can be found on the Internet. One of them is the Sandcastle Help File Builder (SHFB) and you can download it at:

http://www.codeplex.com/SHFB

SHFB is very easy to use. In order to build a documentation (.chm) file you need to follow a few simple steps:

• Create a new project
• Add your assemblies to it (each has to have an .xml documentation file accompanying it)
• Build/Dependencies option – add all assemblies your assemblies depend on
• Build/Framework Version option – select framework version
• Help File/Presentation Style – select vs2005
• Help File/Help Title – select help title for your help file
• Help File/HtmlHelpName – select you help filename
• Set other desired options (most of them is self-explanatory)
• Build help file

SHFB snapshot is shown in the picture bellow:

Finally, after the build process is complete (it may take a long time), the help file is ready! Enjoy!

Below is a list, with descriptions, of the most commonly used XML Documentation Tags.

<summary> / <remarks>
The <summary> tag is used to describe a type or a member. The <remarks> tag is used to add supplemental information to a type or member description.

/// <summary>Type or member description.</summary>
/// <remarks>Supplemental Information.</remarks>

<param>
The <param> tag is used for documenting the method parameter. The <param> tag is always used with the name attribute.

/// <summary>…</summary>
/// <param name=”arg1″>Describe arg1 parameter.</param>
/// <param name=”arg2″>Describe arg2 parameter.</param>
public void XmlDocumentationMethod(string arg1, int arg2) { … } 

<returns>
The <returns> tag is used for describing the return value from a method.

/// <summary>…</summary>
/// <returns>Return value description.</returns>
public int XmlDocumentationMethod ( ) { … }

<see>
The <see> tag is used for adding links to your documentation. It can only be used inside other tags. Also, it has to be used with one of two attributes, href or cref. Href attribute is used for specifying the external hyperlinks. This is actually any link that a browser can recognize, including links to .doc and .pdf documents. Cref attribute is used for specifying an internal hyperlink. Internal hyperlink is linking to any item in the installed MSDN library on your local machine.

You can also use the langword attribute for documenting the language words such as true, false, null, etc.

/// <summary>
/// Various links inside text:
/// <see cref=”System.Exception”/>
/// <see href=”http://www.microsoft.com”/>
/// <see langword=”true”/>
/// </summary>
public void XmlDocumentationMethod ( )  { … }

<exception>
The <exception> tag is used in describing the exceptions that might be thrown by a member.

/// <summary>…</summary>
/// <exception cref=”SerializationException”/>
public void XmlDocumentationMethod ( )
{
            throw new SerializationException ( ) ;
}

 <c> / <code> / <example>
The <c> tag describes the in-line code. The <code> tage describes the code block. The <example> tag introduces the example section.

/// <summary>...</summary>
/// <example>
/// You have to clear the data before you can
/// execute the <c>Helper.Load()</c> to load data.
/// <code>
/// Helper.Clear();
/// Helper.Load();
/// </code>
/// </example>
public void Load() { … }

<list>
The <list> tag is used for formatting the text into a list. The List tag has to be used with the type attribute. The type attribute can be bullet (bulleted list), number (numbered list), or table.

/// <summary>...</summary>
/// <remarks>
/// Bulleted List:
/// <list type="bullet">
/// <item>item 1</item>
/// <item>item 2</item>
/// </list>
/// Numbered List:
/// <list type="number">
/// <item>item 1</item>
/// <item>item 2</item>
/// </list>
/// Table List:
/// <list type="table">
/// <listheader>
///     <term>item</term>
///     <description>description</description>
/// </listheader>
/// <item>
///     <term>item 1</term>
///     <description>description</description>
/// </item>
/// <item>
///     <term>item 2</term>
///     <description>description</description>
/// </item>
/// </list>
/// </remarks>
public void XmlDocumentationMetho ( )  { ... }

Writing code documentation has always been a time consuming process. Additionally, reflecting code changes in the already finished documentation proved to be even more time consuming.

Since the beginning of time, code documentation existed only inside the code itself in the form of the in-line comments. However, modern programming languages introduced syntax for the in-line code comments (XML documentation syntax) and brought the capability of generating the external humanly-readable code documentation from these comments.

Visual Studio has a fully integrated support for the XML documentation. In order to use it inside your .NET project you need to enable it on the Build tab of the Properties page of the project.

Once you build the project with the XML documentation option enabled, a list of warnings will be populated with the additional warnings informing you about the missing XML comments.

You can remove these warnings by simply adding the XML comments to each of the publicly visible types from the list. To add XML comment to the publicly visible type, simply type /// on top of it. Visual Studio will automatically generate the required XML comment syntax and all that is left for you to do is to describe it.

XML documentation supports a wide range of the XML tags used for formatting. I will describe these tags in detail in the second part of this post.