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:

/// <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:

  • 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 that assembly.

  • Third-party tools can transform an XML file into an HTML help file.

Standard XML Documentation Tags

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.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset