Supported XML Code Comments

This page contains a full list of all of the suppored XML code comments with examples of usage.

The Live Documenter supports all of the recommended tags for XML code comments.

• <c>
• <code>
• <example>
• <exception>
• <list>
• <para>
• <param>
• <paramref>
• <remarks>
• <returns>
• <see>
• <seealso>
• <summary>
• <typeparam>
• <typeparamref>
• <value>

Further the following elements are supported by Live Documenter to enable more control over your documentation.

• <b>
• <i>

<c>

An inline element that represents text that should be considered as code.

<c>text</c>

Parameters

text

The text to be treated as inline code.

Example

/// <remarks>
///   <para>This is an <c>inline text</c> c element in a remark.</para>
/// </remarks>

<code>

Element that describes a multi-line code block.

<code>content</code>

Parameters

content

The text to be treated as code.

Example

/// <remarks>
///   <code>
/// // an example of code block
/// public void SomeCode { get; set; }
///   </code>
/// </remarks>
public void TestMethod() { }

<example>

Element that describes a code example.

<example>content</example>

Parameters

example

The description and code sample.

Example

/// <example>
///   <para>A description of the following code block.</para>
///   <code>
/// // an example of code block
/// public void SomeCode { get; set; }
///   </code>
/// </example>
public void TestMethod() { }

<exception>

Element that describes a an exception that can be thrown.

<exception cref="member">description</exception>

Parameters

cref=”member”

A reference to an exception that is available from the current compilation environment. description

The description of the exception

Example

/// <exception cref="MyNamespace.CustomException">A description of the exception.</exception>
public void TestMethod() { }

<list>

Element that describes a list of items or tabular data.

<list type="bullet | number | table">
  <listheader>
    <term>term</term>
    <description>description</description>
  </listheader>
  <item>
    <term></term>
    <description></description>
  </item>
</list>

Parameters

term

A term to define which will be described in the description. description

A description of the term

Example

/// <remarks>
///   <list type="number">
///     <item>
///       <term>Item 1.</term>
///     </item>
///     <item>
///       <term>Item 2.</term>
///     </item>
///   </list>
/// </remarks>
public void TestMethod() { }

Live Documenter supports simplified versions of the list element when you are defining simple lists. Further when no type attribute is specified Live Documenter will default to the <code>bullet</code> type.

/// <remarks>
///   <list>
///     <item>Bulleted item 1</item>
///     <item>Bulleted itme 2</item>
///   </list>
/// </remarks>
public void TestMethod() { }

<para>

Element that describes a paragraph.

<para>content</para>

Parameters

content

The content of the paragraph.

Example

/// <remarks>
///   <para>A paragraph of text.</para>
/// </remarks>
public void TestMethod() { }

<param>

Element that allows the description of a parameter.

<param name="name">description</param>

Parameters

name="name"

The name of the parameter to describe.

description

The description of the parameter.

Example

/// <param name="aString">A string.</param>
public void TestMethod(string aString) { }

<paramref>

An inline element that refers to a parameter.

<paramref name="name" />

Parameters

name="name"

The name of the parameter to describe.

Example

/// <remarks>
///   The <paramref name="aString" /> parameter is required.
/// </remarks>
/// <param name="aString">A string.</param>
public void TestMethod(string aString) { }

<permission>

An element that refers to a parameter.

<permission cref="member">desription</permission>

Parameters

cref="member"

The name of the parameter to describe.

description

A description of the permission.

Example

/// <permission cref="System.Security.PermissionSet">Everyone can access this method.</param>
public void TestMethod() { }

<remarks>

A block level element that provides supplementary remarks.

<remarks>description</remarks>

Parameters

description

A description of the member.

Example

/// <remarks>Everyone can access this method.</remarks>
public void TestMethod() { }

<returns>

A block level element that provides information about the return value.

<returns>description</returns>

Parameters

returns

A description of the member.

Example

/// <returns>Returns a string.</returns>
public string TestMethod() { }

<see>

An inline element that refers to another member in the compilation environment.

<see cref="member" />

Parameters

cref="member"

The member from the current compilation environment.

Example

/// <remarks>
///   <para>This is a method that uses the <see cref="System.String" /> class.</para>
/// </remarks>
public void TestMethod() { }

<seealso>

An element that refers to another member in the compilation environment which will be displayed in a seealso section.

<seealso cref="member" />

Parameters

cref="member"

The member from the current compilation environment.

Example

/// <seealso cref="System.String" />
public void TestMethod() { }

<summary>

A block level element that provides summary of the member.

<summary>description</summary>

Parameters

description

A description of the member.

Example

/// <summary>Everyone can access this method.</summary>
public void TestMethod() { }

<typeparam>

Element that allows the description of a parameter.

<typeparam name="name">description</typeparam>

Parameters

name="name"

The name of the parameter to describe.

description

The description of the parameter.

Example

/// <typeparam name="T">The element type to return.</typeparam>
public T TestMethod<T>() { }

<typeparamref>

An inline element that refers to a type parameter.

<typeparamref name="name" />

Parameters

name="name"

The name of the type parameter to describe.

Example

/// <remarks>
///   The <typeparamref name="element" /> parameter can be anything.
/// </remarks>
public void TestMethod<T>(T element) { }

<value>

A block level element that provides information about the value a property represents.

<value>description</value>

Parameters

description

A description of the value the property represents.

Example

/// <value>Returns a string.</value>
public string TestProperty { get; set; }

<b>

An inline element that represents text that should be considered strong or bold.

<b>text</b>

Parameters

text

The text to be treated as bold/strong.

Example

/// <summary>This <b>text</b> should be treated as important.</summary>
/// <remarks>
///   <para>This is an <b>inline text</b> b element in a remark.</para>
/// </remarks>
public void TestMethod() { }

<i>

An inline element that represents text that should be considered important.

<i>text</i>

Parameters

text

The text to be treated as important.

Example

/// <remarks>
///   <para>This is an <i>inline text</i> i element in a remark.</para>
/// </remarks>
public void TestMethod() { }