.NET 1.1+

XML Documentation Comments (2)

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 Structures

Structures can be given a summary description in the same manner as classes. Try creating the structure below. As before, start by adding the declaration before moving to the preceding line and typing "///". You can then fill in the summary.

/// <summary>
/// Holds the calculator memory value.
/// </summary>
public struct CalculatorMemory
{
}

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; }
}