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 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:
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 (cref
refers to the exception type).
<permission>
<permission [cref="type"
]>...</permission>
Indicates an IPermission
type 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>
tags).
<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>
Merges an external XML file that contains documentation. The path attribute denotes an XPath query to a specific element in that file.