Documenting C# code with XML Comments

This article explains an easy and effective way of documenting your C# code. XML comments are the solution for generating a clean documentation for your code. Visual Studio environment allows you to generate a documentation file for your project. It helps your teammates and other people who using your code.

This post will explain how to use XML comments in code and how to generate XML help documents from those comments.

XML Comment Basics

XML comments can be used to all types except namespaces. The types can be Class,Module,Interface, Enum, properties, events and methods.

XML comments are inserted inline, directly in your source code. To insert an XML comment type three single “///”  immediately above definition.

/// <summary>
/// Executes the sachet rule.
/// </summary>
/// <param name="inputRow">Input row of data.</param>        
/// <returns>True, if sachet exists else false.</returns>
public override bool Execute(System.Collections.Generic.Dictionary<string, string>
 inputRow)
{
    if (!String.IsNullOrEmpty(inputRow["DOSEQTY"]) && inputRow["DOSEQTY"].
        IndexOf("Sachet", StringComparison.OrdinalIgnoreCase) > -1)
    {                
        return true;
    }

    return false;
}

XML Comment in intellisense.

You can add elements that were not in the original XML skeleton. A list of common tags will appear in an IntelliSense  pop-up menu as shown in above figure.

Customizing XML Comments

Visual Studio provides a way to customize the default XML skeleton. Create .xml that includes your default comment templates. Save the file to the appropriate location based on your windows version.

Example: In Visual Studio 2008 the file has to save in the following path

“C:\Documents and Settings\<user>\Application Data\Microsoft\Visual Studio\9.0”.

Generating the XML Documentation File

The Visual Sharp compiler generates an XML document for your assembly with all the XML comments defined in the code. The sample Generated XML Document Excerpt as follows

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Microsoft.Cui.Data</name>
    </assembly>
    <members>
        <member name="T:Microsoft.Cui.Data.RuleStrategy">
            <summary>
            Rules strategy.
            </summary>
        </member>
        <member name="F:Microsoft.Cui.Data.RuleStrategy.ValidSeparator">
            <summary>
            Valid separator between fields.
            </summary>
        </member>
        
    </members>
</doc>

The Visual Studio 2010 editor is rewritten using Windows Presentation Foundation[WPF] and allows for rich visualizations. There is a new component named Managed Extensibility Framework(MEF) which makes it easier for registering add-ins with Visual Studio.

Source: MSDN Magazine may 2009