Cross-References
When you create XML documentation for your code library and compile it into HTML help files using tools such as Sandcastle Help File Builder, the generated help files include hyperlinks between pages. These include links between namespaces and their contained types, links between classes and their members, and external links from your code's documentation to Microsoft Developer Network (MSDN) web pages for standard .NET framework types and members. All of these hyperlinks allow users of your code to quickly navigate to the information that they require.
In addition to the hyperlinks that are added automatically, you can add your own cross-references to XML documentation. These can link to your own types or members, or to those of the .NET framework that can be viewed in the MSDN web site. Incorporating such cross-references is achieved with the addition of four XML tags. We'll look at each of these in this article.
To demonstrate the cross-reference capabilities we'll use a simple class that already includes summary information and descriptions for method parameters and type parameters. We'll modify the comments to add extra links. You can compile the code and documentation for each of the examples to see the results.
NB: The code for the class is not implemented as we are focussing on the documentation only.
/// <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 Priority enum.<para/>
/// Use Enqueue and Dequeue to control the queue's contents.
/// </summary>
/// <typeparam name="T">The type of the items in the buffer.</typeparam>
public class PriorityQueue<T>
{
/// <summary>
/// Adds an item of the generic type to
/// the queue using a 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); }
}<see> Tag
The first type of cross-reference we'll look at uses the see tag. This allows you to create a link within the text of another XML documentation tag. The link's target can be any type or member, either from your own code or from the .NET framework, or can be to an external resource using a Uniform Resource Locator (URL). The target is defined using either a cref or href attribute.
cref Attribute
When you wish to create a link to a type or a member, you use the cref attribute, which is an abbreviation for code reference. In its simplest form, the attribute holds the name of the item to which you wish to link. When the documentation is created, this name is resolved and an appropriate link can be generated. The following shows a cref attribute that can be used within the PriorityQueue class to reference the Enqueue method:
When you want to link to more distant items you need to provide the fully qualified name of the target. For example, this cref links to the File class in the System.IO namespace:
You can be more specific about target methods and constructors by specifying the parameter types they use. This is important when linking to a specific overloaded version of a method. For example, the next cref sample links to the File class's OpenText method that accepts a single string parameter.
cref="System.IO.File.OpenText(string)"
If you wish to link to generic types and generic methods, you can include the type parameters in the reference. The type arguments should be specified within braces, rather than angle brackets. For example, the following cref targets the System.Collections.Generic.Queue<T> generic class:
cref="System.Collections.Generic.Queue{T}"When you create a cross-reference using a cref attribute and do not include any further details, the text of the link will be defaulted to that in the cref attribute. This means that the following tag will cause the generation of a link with the text, "Enqueue".
If you wish to change the text that is displayed within the help file, you can create an XML element that contains inner text. This becomes the text of the final hyperlink. The following code creates a link to the description of the Enqueue method with the text, "the Enqueue method".
<see cref="Enqueue">the Enqueue method</see>
href Attribute
Sometimes you will wish to create a hyperlink within your documentation that does not target another code element. In these cases you can provide the URL of a web page that will become the link's target. This is achieved by providing a href attribute instead of cref, as in the following example:
<see href="http://www.blackwasp.co.uk">BlackWasp</see>
Examples
We can now add several see tags to the documentation of our test class. In the code below the summary of the class includes links to the Priority enumeration, which is not shown in the sample code, and the Enqueue and Dequeue methods. The Enqueue method's summary also links to the Priority enumeration.
/// <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>
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); }
}4 August 2012