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+

The XML Documentation Value Tag

When generating documentation using XML documentation comments, properties can be described using the standard summary tag. They should also include the value tag, which describes the value held in the property.

Property Documentation

As we've seen in early articles, types and their members can be described using XML documentation comments. These comments can then be compiled into help files that explain the usage of your code libraries.

One of the more commonly used tags is summary. It can be applied to classes, structures and all of their constituent members. The tag is used to provide a description of the item and, once compiled into a help file, the summary is the first text seen on a help page. When you are documenting a property, another tag can be used to provide additional information about the value that a property returns, or that you can set in write-only properties. This is the value tag. When included in a help file built with Sandcastle, the information from the value tag appears beneath the syntax of the property.

We can demonstrate this with a sample property, as in the following code. Here the summary describes the usage of the property and the value tag describes the value in its field.

/// <summary>
/// Provides a queue of any type. Items can be assigned a priority.
/// Elements with higher priorities are dequeued before those with a
/// lower priority.<para/>
/// </summary>
/// <typeparam name="T">The type of the items in the buffer.</typeparam>
public class PriorityQueue<T>
{
    int _maxLength;

    /// <summary>
    /// Gets or sets the number of items that can be held in the queue.
    /// </summary>
    /// <value>The maximum number of items in the queue.</value>
    public int MaxLength
    {
        get { return _maxLength; }
        set { _maxLength = value; }
    }
}

If you compile a help file for the above code, the page for the MaxLength property appears as follows. Note the Field Value section, which contains the information from the value tag.

Property Value in XML Documentation

14 August 2012