Table 21-1. Predefined XML tags
|
|
<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 ('').
|
