.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.

Adding a Numbered List

Simple lists and definition lists that use bullets can be made into numeric lists by changing the list type attribute from "bullet" to "number". Aside from replacing the bullet symbol with a number, the list's output is unchanged. The sample comments below create a numbered list:

/// <summary>
/// An enumeration containing the available robot actions. The available actions are:
/// <list type="number">
/// <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>

Compiling the above into a help file gives the following results.

Adding a Table

Lists are useful when the information to be presented is simple. In many cases you will have more structured information that a list cannot easily display whilst retaining legibility. In these situations you can include a table with multiple rows and columns.

Tables are declare using the "list" element with the "type" attribute set to "table". Each row of the table is defined within an "item" tag as before. However, instead of providing a description and an optional term, you specify one term for each column of the table in each item element. So, if the table has three columns, each item will contain three terms.

In addition to the items, you can include "listheader" elements. The content of a listheader is defined in the same manner as that of an item. The difference is that listheader elements are rendered as column headers in the final help file.

Imagine that the robot controlled using the RobotAction enumeration had a different power consumption according to the action being taken. We may want to display the power usage in a table, alongside the action name and description that we've previously shown in lists. You can see such a table defined in the comments below. Note that the first row of the table is a header row, using the "listheader" element, with three terms defining the three column headings. The table's content rows are declared using the item elements that follow.

/// <summary>
/// An enumeration containing the available robot actions. The available actions are:
/// <list type="table">
/// <listheader>
/// <term>Action</term>
/// <term>Description</term>
/// <term>Power Consumption</term>
/// </listheader>
/// <item>
/// <term>Forward</term>
/// <term>Move forwards in a straight line.</term>
/// <term>50W</term>
/// </item>
/// <item>
/// <term>Backward</term>
/// <term>Move backwards in a straight line.</term>
/// <term>50W</term>
/// </item>
/// <item>
/// <term>RotateLeft</term>
/// <term>Rotate to the left.</term>
/// <term>30W</term>
/// </item>
/// <item>
/// <term>RotateRight</term>
/// <term>Rotate to the right.</term>
/// <term>30W</term>
/// </item>
/// <item>
/// <term>Dig</term>
/// <term>Tells the robot to dig and obtain a soil sample.</term>
/// <term>800W</term>
/// </item>
/// </list>
/// </summary>

Once compiled into a help file, the resultant table appears as shown below: