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 Cross-References

One of the key benefits of providing code documentation using HTML Help is that the pages within the help files link to each other. Many links are added automatically by tools such as Sandcastle. It is possible to create additional links using manually.

<seealso> Tag

If you are a user of MSDN you will have seen the collapsible "See Also" section that appears in documentation pages. You can use the seealso element to create entries in this section using cref or href attributes in the same manner as with the see tag. The seealso tag should appear at the same level as the summary, not within the text of other tags.

The updated code below includes a seealso element in the documentation for the PriorityQueue class.

/// <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/>
/// Priorities are defined using the <see cref="Priority">Priority enum</see>.<para/>
/// Use <see cref="Enqueue">Enqueue</see> and <see cref="Dequeue">Dequeue</see>
/// to control the queue's contents.
/// </summary>
/// <typeparam name="T">The type of the items in the buffer.</typeparam>
/// <seealso cref="System.Collections.Generic.Queue{T}">Generic Queue Class</seealso>
public class PriorityQueue<T>
{
    /// <summary>
    /// Adds an item of the generic type to
    /// the queue using a <see cref="Priority"/> value provided to
    /// the priority parameter.
    /// </summary>
    /// <param name="item">The item to enqueue.</param>
    /// <param name="priority">The priority of the item.</param>
    public void Enqueue(T item, Priority priority) { }
        
    /// <summary>
    /// Dequeues the first of the highest priority items in the queue.
    /// </summary>
    /// <returns>The item.</returns>
    public T Dequeue() { return default(T); }
}

<paramref> and <typeparamref> Tags

The final two documentation tags that we'll consider in this article allow you to create cross-references for parameters. The paramref tag includes a cref attribute that references a parameter. The typeparamref is similar, except that the target is a generic type parameter. When you build the documentation using Sandcastle, these tags are not converted into hyperlinks. However, the text is formatted differently to highlight it.

The following code adds a type parameter cross-reference in the class's summary that points to the T type parameter. The Enqueue method's summary includes another typeparamref and a paramref tag for the priority parameter.

/// <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/>
/// Priorities are defined using the <see cref="Priority">Priority enum</see>.<para/>
/// Use <see cref="Enqueue">Enqueue</see> and <see cref="Dequeue">Dequeue</see>
/// to control the queue's contents.
/// </summary>
/// <typeparam name="T">The type of the items in the buffer.</typeparam>
/// <seealso cref="System.Collections.Generic.Queue{T}">Generic Queue Class</seealso>
public class PriorityQueue<T>
{
    /// <summary>
    /// Adds an item of the <typeparamref name="T">generic type</typeparamref> to
    /// the queue using a <see cref="Priority"/> value provided to
    /// the <paramref name="priority"/> parameter.
    /// </summary>
    /// <param name="item">The item to enqueue.</param>
    /// <param name="priority">The priority of the item.</param>
    public void Enqueue(T item, Priority priority) { }
        
    /// <summary>
    /// Dequeues the first of the highest priority items in the queue.
    /// </summary>
    /// <returns>The item.</returns>
    public T Dequeue() { return default(T); }
}
4 August 2012