Common XML Documentation Tags
Below is a list, with descriptions, of the most commonly used XML Documentation Tags.
<summary> / <remarks>
The <summary> tag is used to describe a type or a member. The <remarks> tag is used to add supplemental information to a type or member description.
/// <summary>Type or member description.</summary>
/// <remarks>Supplemental Information.</remarks>
<param>
The <param> tag is used for documenting the method parameter. The <param> tag is always used with the name attribute.
/// <summary>…</summary>
/// <param name=”arg1″>Describe arg1 parameter.</param>
/// <param name=”arg2″>Describe arg2 parameter.</param>
public void XmlDocumentationMethod(string arg1, int arg2) { … }
<returns>
The <returns> tag is used for describing the return value from a method.
/// <summary>…</summary>
/// <returns>Return value description.</returns>
public int XmlDocumentationMethod ( ) { … }
<see>
The <see> tag is used for adding links to your documentation. It can only be used inside other tags. Also, it has to be used with one of two attributes, href or cref. Href attribute is used for specifying the external hyperlinks. This is actually any link that a browser can recognize, including links to .doc and .pdf documents. Cref attribute is used for specifying an internal hyperlink. Internal hyperlink is linking to any item in the installed MSDN library on your local machine.
You can also use the langword attribute for documenting the language words such as true, false, null, etc.
/// <summary>
/// Various links inside text:
/// <see cref=”System.Exception”/>
/// <see href=”http://www.microsoft.com”/>
/// <see langword=”true”/>
/// </summary>
public void XmlDocumentationMethod ( ) { … }
<exception>
The <exception> tag is used in describing the exceptions that might be thrown by a member.
/// <summary>…</summary>
/// <exception cref=”SerializationException”/>
public void XmlDocumentationMethod ( )
{
throw new SerializationException ( ) ;
}
<c> / <code> / <example>
The <c> tag describes the in-line code. The <code> tage describes the code block. The <example> tag introduces the example section.
/// <summary>...</summary>
/// <example>
/// You have to clear the data before you can
/// execute the <c>Helper.Load()</c> to load data.
/// <code>
/// Helper.Clear();
/// Helper.Load();
/// </code>
/// </example>
public void Load() { … }
<list>
The <list> tag is used for formatting the text into a list. The List tag has to be used with the type attribute. The type attribute can be bullet (bulleted list), number (numbered list), or table.
/// <summary>...</summary>
/// <remarks>
/// Bulleted List:
/// <list type="bullet">
/// <item>item 1</item>
/// <item>item 2</item>
/// </list>
/// Numbered List:
/// <list type="number">
/// <item>item 1</item>
/// <item>item 2</item>
/// </list>
/// Table List:
/// <list type="table">
/// <listheader>
/// <term>item</term>
/// <description>description</description>
/// </listheader>
/// <item>
/// <term>item 1</term>
/// <description>description</description>
/// </item>
/// <item>
/// <term>item 2</term>
/// <description>description</description>
/// </item>
/// </list>
/// </remarks>
public void XmlDocumentationMetho ( ) { ... }
Tags: xml