C# XML Documentation
Description
A documentation comment is a piece of embedded XML that documents a type or member.
Syntax
A documentation comment comes immediately before a type or member declaration, and starts with three slashes:
/// <summary>Cancels a running query.</summary>
public void Cancel() { ... }
Multiline comments can be done either like this:
/// <summary>
/// Cancels a running query
/// </summary>
public void Cancel() { ... }
or like this (notice the extra star at the start):
/**
<summary> Cancels a running query. </summary>
*/
public void Cancel() { ... }
Standard Tag
Here are the standard XML tags that Visual Studio and documentation generators recognize:
<summary>...</summary> A single phrase or sentence summary.
<remarks>...</remarks> Additional text that describes the type or member.
<param name="name">...</param> Explains a parameter on a method.
<returns>...</returns> Explains the return value for a method.
<exception [cref="type"]>...</exception> Lists an exception that a method may throw.
<permission [cref="type"]>...</permission> Indicates an IPermission type required by the documented type or member.
<example>...</example> Denotes an example.
<c>...</c> Indicates an inline code snippet.
<code>...</code> Indicates a multiline code sample.
<see cref="member">...</see> Inserts an inline cross-reference to another type or member.
<seealso cref="member">...</seealso> Cross-references another type or member.
<paramref name="name"/> References a parameter from within a <summary> or <remarks> tag.
<list type=[ bullet | number | table ]> Instructs documentation generators to emit a bulleted, numbered, or table-style list.
<listheader>// ww w . j ava 2 s . co m
<term>...</term>
<description>...</description>
</listheader>
<item>
<term>...</term>
<description>...</description>
</item>
</list>
<para>...</para> Format the contents into a separate paragraph.
<include> Merges an external XML file that contains documentation.
Example
using System;//w w w .ja v a 2 s . c o m
namespace DocumentationCommentsExample
{
/// <summary>
/// A documentation sample - the short description goes here
/// </summary>
/// <remarks>Where a longer description would go</remarks>
class ClassExample
{
/// <summary>
/// A member variable
/// </summary>
private string m_str;
/// <summary>
/// A method example
/// </summary>
/// <param name="val">a new value to be saved</param>
/// <returns>the length of the string</returns>
public int MethodExample( string val )
{
m_str = val;
return val.Length;
}
}
}
If you compile with the /doc directive, the compiler extracts and collates documentation comments into a single XML file.
Example 2
using System;//from w ww . j a v a 2 s. c o m
namespace Payroll
{
/// <summary>
/// Document for Employee class
/// See a cross reference <see cref="String">string</see>
/// </summary>
public class Employee
{
/// <summary>
/// Comment for the constructor
/// <paramref name="name">name2</paramref> is a string.
/// </summary>
/// <param name="id">Employee id number</param>
/// <param name="name">Employee Name</param>
public Employee(int id, string name)
{
this.id = id;
this.name = name;
}
/// <summary>
/// Comments for another constructor
/// </summary>
/// <remarks>
/// <seealso cref="Employee(int, string)">Employee(int, string)</seealso>
/// </remarks>
public Employee()
{
id = -1;
name = null;
}
int id;
string name;
}
}