.NET 2.0+

Creating Type Parameter Documentation

by Richard Carr, published at http://www.blackwasp.co.uk/TypeParamDocumentation.aspx

When creating help files to explain the use of code libraries using XML documentation comments, generic types and methods can include additional information that describes their type parameters. This is achieved with the use of the typeparam element.

Type Parameters

When you create generic types or generic methods, you may add XML documentation that describes those elements. This will generally include a summary and, for methods, descriptions of the parameters and the method's return value. You can also include information about the type parameters for generic versions of these items, to describe the usage of those type arguments and details of any of their constraints.

To add a type parameter description to your documentation, you use the typeparam tag. This should include a name attribute with a value that matches the declared name of the argument being described. The text describing the type parameter should appear as the inner text of the XML element.

The code below shows an example generic class that contains a type parameter description.

/// <summary>
/// Provides a circular buffer of any type. Items added to the buffer
/// beyond its maximum size overwrite the oldest items.
/// </summary>
/// <typeparam name="T">The type of the items in the buffer.</typeparam>
public class CircularBuffer<T>
{
}

When compiled into a help file using Sandcastle, the type parameters appear in their own collapsible section, as seen at the bottom of the image below: