list

This element describes content that should be displayed as a list or a table.

Syntax

This inline block element can be used within any other element.

 
<list type="bullet">
  <item>
    <term>Optional term</term>
    <description>Required description.  If term is omitted, the description can be
listed as the item element's inner text.</description>
  </item>
  ...
</list>

or

<list type="number" [start="###"]>
  <item>
    <term>Optional term</term>
    <description>Required description.  If term is omitted, the description can be
listed as the item element's inner text.</description>
  </item>
  ...
</list>

or

<list type="definition">
  <item>
    <term>Required term</term>
    <description>Required description</description>
  </item>
  ...
</list>

or

<list type="table">
  <listheader>
    <term>Multi-column table header</term>
    <term>Add additional term or description elements to create new header columns</term>
    ...
  </listheader>
  <item>
    <description>Multi-column table</description>
    <description>Add additional term or description elements to create new columns</description>
    ...
  </item>
  ...
</list>

The type attribute defines the list type. The list type value should be one of the values shown below. The list item terms and descriptions can be any valid inline or block XML comments similar to a remarks element.

  Important

The type attribute value is case-sensitive. Unrecognized values will default to the bullet list style.

The type attribute can be any of the following values. The requirements of each format are noted in the description.

List Type

Description

bullet

This renders a bulleted list. Each item element will render a new bulleted item. If term and description elements are omitted, the inner text is rendered after the bullet point. The same thing happens if a description element is included by itself. If both a term and a description element are present, the term is highlighted and separated from the description by a dash.

number

This renders a numbered list. Each item element will render a new numbered item. If term and description elements are omitted, the inner text is rendered after the number. The same thing happens if a description element is included by itself. If both a term and a description element are present, the term is highlighted and separated from the description by a dash.

The number style supports an optional start attribute that can be used to indicate the starting number for the numbered list. This lets you create a list at a later point in the topic that continues numbering from the end point of a prior list. You are responsible for providing the appropriate starting number for the new list.

  Note

start is a custom attribute implemented by Sandcastle.

definition

A definition list. A term and description element are required within each item element. The term is highlighted and rendered on a separate line with the description following in a new paragraph.

table

A multi-column table. The item elements create new rows in the table. With this type, the optional listheader element can be used to define the column headers. Use a term or a description element to define the columns in the listheader and each item element.

Examples

 
/// <summary>
/// This method shows various examples of the <c>list</c> XML comments element.
/// </summary>
/// <remarks>
/// <para>A simple bulleted list.  The <c>term</c> and <c>description</c>
/// elements are optional for simple string descriptions.</para>
/// 
/// <list type="bullet">
///   <item>First item</item>
///   <item>Second item</item>
///   <item>Third item</item>
/// </list>
///
/// <para>Bullet list with terms and definitions.  The term is highlighted and
/// separated from the definition with a dash.</para>
/// 
/// <list type="bullet">
///   <item>
///     <term>maxLen</term>
///     <description>field must contain no more than the specified number
/// of characters</description>
///   </item>
///   <item>
///     <term>minLen</term>
///     <description>field must contain at least the specified number
/// of characters</description>
///   </item>
///   <item>
///     <term>maxVal</term>
///     <description>field must contain a number that is no larger than the
/// specified value</description>
///   </item>
///   <item>
///     <term>minVal</term>
///     <description>field must contain a number that is no smaller than the
/// specified value</description>
///   </item>
///   <item>
///     <term>pattern</term>
///     <description>field must match the specified regular expression
/// </description>
///   </item>
/// </list>
/// 
/// <para>A simple numbered list.  The <c>term</c> and <c>description</c>
/// elements are optional for simple string descriptions.</para>
/// 
/// <list type="number">
///   <item>First item</item>
///   <item>Second item</item>
///   <item>Third item</item>
/// </list>
/// 
/// <para>This next numbered list uses the optional <c>start</c> attribute to
/// continue numbering where the last one left off.</para>
/// 
/// <list type="number" start="4">
///   <item>Fourth item</item>
///   <item>Fifth item</item>
///   <item>Sixth item</item>
/// </list>
/// 
/// <para>Numbered list with terms and definitions.</para>
/// 
/// <list type="number">
///   <item>
///     <term>maxLen</term>
///     <description>field must contain no more than the specified number
/// of characters</description>
///   </item>
///   <item>
///     <term>minLen</term>
///     <description>field must contain at least the specified number
/// of characters</description>
///   </item>
///   <item>
///     <term>maxVal</term>
///     <description>field must contain a number that is no larger than the
/// specified value</description>
///   </item>
///   <item>
///     <term>minVal</term>
///     <description>field must contain a number that is no smaller than the
/// specified value</description>
///   </item>
///   <item>
///     <term>pattern</term>
///     <description>field must match the specified regular expression
/// </description>
///   </item>
/// </list>
/// 
/// <para>Definition list.</para>
/// 
/// <list type="definition">
///   <item>
///     <term>maxLen</term>
///     <description>field must contain no more than the specified number
/// of characters</description>
///   </item>
///   <item>
///     <term>minLen</term>
///     <description>field must contain at least the specified number
/// of characters</description>
///   </item>
///   <item>
///     <term>maxVal</term>
///     <description>field must contain a number that is no larger than the
/// specified value</description>
///   </item>
///   <item>
///     <term>minVal</term>
///     <description>field must contain a number that is no smaller than the
/// specified value</description>
///   </item>
///   <item>
///     <term>pattern</term>
///     <description>field must match the specified regular expression
/// </description>
///   </item>
/// </list>
///
/// <para>Two-column table list with terms and definitions.</para>
/// 
/// <list type="table">
///   <listheader>
///     <term>Item</term>
///     <description>Description</description>
///   </listheader>
///   <item>
///     <term>maxLen</term>
///     <description>field must contain no more than the specified number
/// of characters</description>
///   </item>
///   <item>
///     <term>minLen</term>
///     <description>field must contain at least the specified number
/// of characters</description>
///   </item>
///   <item>
///     <term>maxVal</term>
///     <description>field must contain a number that is no larger than the
/// specified value</description>
///   </item>
///   <item>
///     <term>minVal</term>
///     <description>field must contain a number that is no smaller than the
/// specified value</description>
///   </item>
///   <item>
///     <term>pattern</term>
///     <description>field must match the specified regular expression
/// </description>
///   </item>
/// </list>
/// 
/// <para>A table with multiple columns.  <c>term</c> or <c>description</c>
/// can be used to create the columns in each row.</para>
/// 
/// <list type="table">
///   <listheader>
///     <term>Column 1</term>
///     <term>Column 2</term>
///     <term>Column 3</term>
///     <term>Column 4</term>
///   </listheader>
///   <item>
///     <term>R1, C1</term>
///     <term>R1, C2</term>
///     <term>R1, C3</term>
///     <term>R1, C4</term>
///   </item>
///   <item>
///     <description>R2, C1</description>
///     <description>R2, C2</description>
///     <description>R2, C3</description>
///     <description>R2, C4</description>
///   </item>
/// </list>
/// </remarks>
/// <conceptualLink target="e433d846-db15-4ac8-a5f5-f3428609ae6c" />
public void VariousListExamples()
{
}

See Also

Reference

Other Resources