Chapter 21. XML Documentation Tag Reference

Table 21-1 lists the predefined set of XML tags that can be used to mark up the descriptive text. Table 21-2 lists possible prefixes for type and member cross-references.

Table 21-1. Predefined XML tags

Tag

Description

<summary>

 <summary>   description   </summary> 

Describes a type or member. Typically, this contains the description of a member at a fairly high level.

<remarks>

 <remarks>   description   </remarks> 

Provides additional information regarding a particular member. Information about side effects within the method, or particular behavior that may not otherwise be intuitive (such as the idea that this method may throw an ArrayOutOfBoundsException if a parameter is greater than 5) should be listed here.

<param>

 <param name="name">   description   </param> 

Describes a parameter on a method. The name attribute is mandatory and must refer to a parameter on the method. If this tag is applied to any parameter on a method, all parameters on that method must be documented. You must enclose name in double quotation marks ("").

<returns>

 <returns>   description   </returns> 

This tag describes the return values for a method.

<exception>

 <exception [cref="   type   "]>   description   </exception> 

Describes the exceptions a method may throw. If present, the optional cref attribute should refer to the type of exception. You must enclose type in double quotation marks ("").

<permission>

 <permission [cref="   type   "]>   description   </permission> 

Describes the permission requirements for a type or member. If present, the optional cref attribute should refer to the type that represents the permission set required by the member, although the compiler doesn't validate this. You must enclose type in double quotation marks ("").

<example>

 <example>   description   </example> 

Provide a description and sample source code explaining the use of a type or member. Typically, the <example> tag provides the description and contains the <c> and <code> tags (described next ), although these can also be used independently.

<c>

 <c>   code   </c> 

Indicates an inline code snippet. Typically, this is used inside of an <example> block (just described).

<code>

 <code>   code   </code> 

Used to indicate multiline code snippets. Again, typically used inside of an <example> block.

<see>

 <see cref="   member   ">   text   </see> 

Identifies cross-references in the documentation to other types or members . Typically, the <see> tag is used inline within a description (as opposed to the < seealso > tag, below, which is broken out into a separate "See Also" section). These tags are useful because they allow tools to generate cross-references, indexes, and hyperlinked views of the documentation. Member names must be enclosed by double quotation marks ("").

<seealso>

 <seealso cref="   member   ">   text   </seealso> 

Identifies cross-references in the documentation to other types or members. Typically, <seealso> tags are broken out into a separate "See Also" section. These tags are useful because they allow tools to generate cross-references, indexes, and hyperlinked views of the documentation. Member names must be enclosed by double quotation marks ("").

<value>

 <value>   description   </value> 

Describes a property on a class.

<paramref>

 <paramref name="   name   "/> 

Identifies the use of a parameter name within descriptive text, such as <remarks> or <summary> . The name must be enclosed by double quotation marks ("").

<list>

 <list type=[   bullet     number     table   ]>  <listheader>  <term>   name   </term>  <description>   description   </description>  </listheader>  <item>  <term>   name   </term>  <description>   description   </description>  </item> </list> 

Provide hints to documentation generators on how to format the documentation ”in this case as a list of items.

<para>

 <para>   text   </para> 

Sets off the text as a paragraph to documentation generators.

< include >

 <include file='   filename   ' path='   path-to-element   '> 

Specifies an external file that contains documentation and an XPath path to a specific element in that file. For example, a path of docs[@id="001"]/* retrieves whatever is inside of <docs id="001"/> . The filename and path must be enclosed by single quotation marks ('').

Table 21-2. XML type ID prefixes

Prefix

Applied to

N

Namespace

T

Type (class, struct, enum, interface, delegate)

F

Field

P

Property (includes indexers)

M

Method (includes special methods )

E

Event

!

Error



C# in a Nutshell
C # in a Nutshell, Second Edition
ISBN: 0596005261
EAN: 2147483647
Year: 2005
Pages: 963

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net