CSharp/C# Tutorial - C# XML Documentation

• « Previous

A documentation comment is embedded XML that documents a type or member.

A documentation comment comes immediately before a type or member declaration, and starts with three slashes:

/// <summary>Cancels a command.</summary>
public void Cancel() { 
   ... 
}

Multiline comments can be done either like this:

/// <summary>
/// Cancels a command
/// </summary>
public void Cancel() { 
   ... 
}

or We can use the multiline document command /** */:

/**
   <summary> Cancels a command. </summary>
*/
public void Cancel() { 
   ... 
}

If you compile with the /doc directive, the compiler extracts and collates documentation comments into a single XML file.

Standard XML Documentation Tags

Here are the standard XML tags that Visual Studio and documentation generators recognize:

• <summary>...</summary>
  Marks the summary for the type or member; typically a single phrase or sentence.
• <remarks>...</remarks>
  Marks 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>
  Sets an IPermission type required by the documented type or member.
• <example>...</example>
  Marks an example.
• <c>...</c>
  Marks an inline code snippet.
• <code>...</code>
  Marks a multiline code sample.
• <see cref="member">...</see>
  Marks 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 ]>
     <listheader>
        <term>...</term>
        <description>...</description>
     </listheader>
     <item>
        <term>...</term>
        <description>...</description>
     </item>
  </list>
  

  Creates a bulleted, numbered, or table-style list.
• <para>...</para>
  format the contents into a separate paragraph.
• <include file='filename' path='tagpath[@name="id"]'>...</para>
  Merges an external XML file that contains documentation.





• « Previous