XML Documentation
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, it can have single or multi line comments.
Standard XML Documentation Tags
| <summary>…</summary> | Indicates the tool tip that IntelliSense should display for the type or member; typically a single phrase or sentence. |
| <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 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 (cref refers to the exception type). |
| <permission [cref=”type”]>…</permission> | Indicates an IPermission type required by the documented type or member. |
| <example>…</example> | Denotes an example using both text description and source code with <code> tag |
| <c>…</c> | Indicates an inline code snippet usually inside an example block. |
| <code>…</code> | Indicates a multiline code sample, usually inside example block |
| <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> | Instructs documentation generators to emit a bulleted, numbered, or tablestyle list. |
| <para>…</para> | Instructs documentation generators to format the contents into a separate paragraph. |
| <include file=’filename’ path=’tagpath[@name=”id”]’>…</include> | Merges an external XML file that contains documentation. The path attribute denotes an XPath query to a specific element in that file. |
User-Defined Tags
You are free to define your own tags.
Type or Member Cross-References
Type names and type or member cross-references are translated into IDs that uniquely define the type or member.
These names are composed of a prefix that defines what the ID represents and a signature of the type or member.
| N | Namespace |
| T | Type (class, struct, enum, interface, delegate) |
| F | Field |
| P | Property (includes indexers) |
| M | Method (includes special methods) |
| E | Event |
| ! | Error |