.NET 1.1+

Adding Lists and Tables to XML Documentation

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

Bullet lists, numbered lists and tables provide useful ways to provide information about the use of a framework, a single class or a member. These ways of displaying data can be included in XML documentation comments and compiled into help files.

Lists and Tables

Information is often organised into lists or tables to improve its presentation and enable the reader to quickly understand it. When you are documenting a code library using XML documentation comments, it can be useful to include lists and tables within the text. This can be achieved by inserting list elements within the comments and compiling them into a help file using a tool such as Sandcastle Help File Builder (SHFB).

Adding a Bulleted List

When you want to add a simple list to your help file you can either create a bullet list or a numbered list. We'll start by creating the former within the summary section of an enumeration. A lists is defined by adding a list element to the documentation XML. This element must include a "type" attribute, which determines how the final rendered list will be displayed. For a bulleted list, the attribute's value should be set to "bullet".

<list type="bullet">

Each item that you wish to add to the list is included in an "item" element, with the text to appear held within a "description" element. For example:

<item>
    <description>Move forwards in a straight line.</description>
</item>

Let's apply these elements to some C# code. The sample below shows a full summary comment for an enumeration. The enumeration's constants represent the available actions for a remote-controlled robot. The list describes each of the actions in more detail. In a real code library you might wish to move the list item descriptions to the summaries for the individual enumeration members.

/// <summary>
/// An enumeration containing the available robot actions. The available actions are:
/// <list type="bullet">
/// <item>
/// <description>Move forwards in a straight line.</description>
/// </item>
/// <item>
/// <description>Move backwards in a straight line.</description>
/// </item>
/// <item>
/// <description>Rotate to the left.</description>
/// </item>
/// <item>
/// <description>Rotate to the right.</description>
/// </item>
/// <item>
/// <description>Tells the robot to dig and obtain a soil sample.</description>
/// </item>
/// </list>
/// </summary>
public enum RobotAction
{
    Forward = 1,
    Backward,
    RotateLeft,
    RotateRight,
    Dig
}

Once compiled with SHFB, the enumeration's description appears as shown below. The exact styling for the information may vary according to the options you select in the SHFB graphical user interface.

Creating a Definition List

You can create a definition list, which is a set of terminology with linked descriptions, by adding a "term" element within each of the items in your list. The updated comments below add a term element that matches the appropriate RobotAction constant name to every item. Note that the descriptions are unchanged. I have omitted the enumeration code from the example in this case.

/// <summary>
/// An enumeration containing the available robot actions. The available actions are:
/// <list type="bullet">
/// <item>
/// <term>Forward</term>
/// <description>Move forwards in a straight line.</description>
/// </item>
/// <item>
/// <term>Backward</term>
/// <description>Move backwards in a straight line.</description>
/// </item>
/// <item>
/// <term>RotateLeft</term>
/// <description>Rotate to the left.</description>
/// </item>
/// <item>
/// <term>RotateRight</term>
/// <description>Rotate to the right.</description>
/// </item>
/// <item>
/// <term>Dig</term>
/// <description>Tells the robot to dig and obtain a soil sample.</description>
/// </item>
/// </list>
/// </summary>

Once compiled into a help file, the terms are highlighted in the bullet list.