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
<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
<para>…</para> Instructs documentation generators to format the contents into a separate
<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

Leave a Reply

Your email address will not be published. Required fields are marked *