A documentation comment is a piece of 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 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() { ... }
If you compile with the /doc
directive, the compiler extracts and collates documentation comments into
a single XML file. This has two main uses:
If placed in the same folder as the compiled assembly, Visual Studio automatically reads the XML file and uses the information to provide IntelliSense member listings to consumers of the assembly of the same name.
Third-party tools (such as Sandcastle and NDoc) can transform an XML file into an HTML help file.
Here are the standard XML tags that Visual Studio and documentation generators recognize:
<summary><summary>...</summary>Indicates the tool tip that IntelliSense should display for the type or member. Typically a single phrase or sentence.
<remarks><remarks>...</remarks>Additional text that describes the type or member. Documentation generators pick this up and merge it into the bulk of a type or member’s description.
<param><param name="name">...</param>Explains a parameter on a method.
<returns><returns>...</returns>Explains the return value for a method.
<exception><exception [cref="type"]>...</exception>Lists an exception that a method may throw (
crefrefers to the exception type).<permission><permission [cref="type"]>...</permission>Indicates an
IPermissiontype required by the documented type or member.<example><example>...</example>Denotes an example (used by documentation generators). This usually contains both description text and source code (source code is typically within a
<c>or<code>tag).<c><c>...</c>Indicates an inline code snippet. This tag is usually used inside an
<example>block.<code><code>...</code>Indicates a multiline code sample. This tag is usually used inside an
<example>block.<see><see cref="member">...</see>Inserts an inline cross-reference to another type or member. HTML documentation generators typically convert this to a hyperlink. The compiler emits a warning if the type or member name is invalid.
<seealso><seealso cref="member">...</seealso>Cross-references another type or member. Documentation generators typically write this into a separate “See Also” section at the bottom of the page.
<paramref><paramref name="name"/>References a parameter from within a
<summary>or<remarks>tag.<list><list type=[ bullet | number | table ]> <listheader> <term>...</term> <description>...</description> </listheader> <item> <term>...</term> <description>...</description> </item> </list>Instructs documentation generators to emit a bulleted, numbered, or table-style list.
<para><para>...</para>Instructs documentation generators to format the contents into a separate paragraph.
<include><include file='filename' path='tagpath[@name="id"]'>...</para>Merges an external XML file that contains documentation. The path attribute denotes an XPath query to a specific element in that file.