BlackWaspTM

This web site uses cookies. By using the site you accept the cookie policy.This message is for compliance with the UK ICO law.

Documentation
.NET 1.1+

XML Documentation Comments

Documentation is important to ensure that developers can quickly learn and use code libraries. With XML documentation comments, the documentation can be embedded within source code using special mark-up that is recognised by Visual Studio's Intellisense.

Documenting Constructors

Constructors add another XML element to the basic documentation comments. As with earlier items, the summary element allows you to include a description of the constructor. You can also use a number of param elements to describe any parameters. Each param element must include a name attribute with a value that matches the name of one of the arguments.

Try adding the constructor shown below to the Calculator class. If you create the constructor first and then add the three slashes that define the documentation comment, you will see that Visual Studio automatically adds both the summary and param tags. For constructors with multiple parameters, several param tags will be created.

/// <summary>
/// Creates a new Calculator.
/// </summary>
/// <param name="scientificMode">If true, the calculator is started in scientific mode.
/// If false, the calculator is started in standard mode.</param>
public Calculator(bool scientificMode)
{
}

Documenting Fields

If desired, you can add XML documentation comments to fields. The following shows a backing store field for a property with a summary defined.

/// <summary>
/// Holds the calculator current working value.
/// </summary>
decimal _value;

Documenting Methods

Methods are documented in a similar manner to constructors, with summary and param elements in the XML comment. If the method returns a value, you can include a returns element that describes the return value. This is shown in the method below, which adds a value to the _value field and returns the newly calculated value.

/// <summary>
/// Adds a value to the working value.
/// </summary>
/// <param name="valueToAdd">The value to be added to the working value.</param>
/// <returns>The new working value in the calculator.</returns>
public decimal Add(decimal valueToAdd)
{
    _value += valueToAdd;
    return _value;
}

Documenting Properties

Properties are simple in comparison with methods so the basic documentation comment only includes a summary element. It is common to specify which of the operations, get and / or set, are supported by the property, as in the following example:

/// <summary>
/// Gets or sets the calculator working value.
/// </summary>
public decimal WorkingValue
{
    get { return _value; }
    set { _value = value; }
}

Documenting Indexers

If you have an indexer, it can be documented in a similar manner to a method. The summary element allows a description to be specified. The param element is used to describe the index parameter, which appears between square brackets, and the returns element adds information relating to the return value.

/// <summary>
/// Returns one of the calculator memory slot values.
/// </summary>
/// <param name="memory">The memory slot number to return.</param>
/// <returns>The memory slots value.</returns>
public decimal this[int memory]
{
    get { return 0M; }
}

Documenting Enumerations

The last element of code that we will consider is the enumeration. To fully document an enumeration you should include a documentation comment above the enum declaration that includes a summary. You should also include a summary for each constant defined in the enumeration. For example:

/// <summary>
/// Defines the buttons on the calculator.
/// </summary>
public enum CalculatorButtons
{
    /// <summary>
    /// The addition button.
    /// </summary>
    Add,

    /// <summary>
    /// The subtraction button.
    /// </summary>
    Subtract,

    /// <summary>
    /// The multiplication button.
    /// </summary>
    Multiply,
        
    /// <summary>
    /// The division button.
    /// </summary>
    Divide
}
3 January 2012