C# and XML - Predefined XML Tags
(Page 3 of 4 )
Here is a list of the predefined set of XML tags that can be used to mark up the descriptive text:
<summary>
<summary>description</summary>
This is the first thing you will see when IntelliSense shows the tool tip for the member.
<remarks>
<remarks>description</remarks>
This is the additional text you will see when IntelliSense shows the tool tip for the member. This tag 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 anArrayOutOfBoundsExceptionif a parameter is greater than 5) is listed here.
<param>
<param name="name">description</param>
This tag describes a parameter on a method. If this tag is applied to any parameter on a method, all of the parameters on that method must be documented.
<returns>
<returns>description</returns>
This tag describes the return value for a method.
<exception>
<exception [cref="type"]>description</exception>
This tag documents the exceptions a method may throw. If present, the optionalcref attribute should refer to the type of the exception. The type name must be enclosed in double quotation marks ("").
<permission>
<permission [cref="type"]>description</permission>
This tag documents the permissions requirement for a type or member. If present, the optionalcrefattribute should refer to the type that represents the permission set required by the member, although the compiler does not validate this. The type name must be enclosed in double quotation marks ("").
<example>
<example>description</example>
This tag provides 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, although they can also be used independently.
<c>
<c>code</c>
This tag indicates an inline code snippet. Typically, this tag is used inside an<example>block (described previously).
<code>
<code>code</code>
This tag is used to indicate multiline code snippets. Again, this is typically used inside an<example>block (described previously).
<see>
<see cref="member">text</see>
This tag 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, which is broken out into a separate “See Also” section). This tag is useful because it allows 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>
This tag identifies cross-references in the documentation to other types or members. Typically,<seealso>tags are broken out into a separate “See Also” section. This tag is useful because it allows 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>
This tag describes a property on a class.
<paramref>
<paramref name="name"/>
This tag identifies the use of a parameter name within descriptive text, such as<remarks>. 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>
This tag provides hints to documentation generators about how to format the documentation—in this case, as a list of items.
<para>
<para>text</para>
This tag sets off the text as a paragraph to documentation generators.
<include>
<include file='filename' path='path-to-element'>
This tag 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<docs id="001"/>. Thefilenameandpathmust be enclosed by single quotation marks (''), but you must use double quotation marks ("") for theidattribute within thepath-to-elementexpression.
Next: User-Defined Tags >>
More C# Articles
More By O'Reilly Media
|
 This article is excerpted from chapter four of C# 3.0 in a Nutshell, Third Edition, A Desktop Quick Reference, written by Joseph Albahari and Ben Albahari (O'Reilly; ISBN: 0596527578). Check it out today at your favorite bookstore. Buy this book now.
|
|
