X hits on this document

986 views

0 shares

0 downloads

0 comments

348 / 396

Appendix ‎A   Documentation comments

The text within documentation comments must be well formed according to the rules of XML (http://www.w3.org/TR/REC-xml). If the XML is ill formed, a warning is generated and the documentation file will contain a comment saying that an error was encountered.

Although developers are free to create their own set of tags, a recommended set is defined in §‎A.2. Some of the recommended tags have special meanings:

The <param> tag is used to describe parameters. If such a tag is used, the documentation generator must verify that the specified parameter exists and that all parameters are described in documentation comments. If such verification fails, the documentation generator issues a warning.

The cref attribute can be attached to any tag to provide a reference to a code element. The documentation generator must verify that this code element exists. If the verification fails, the documentation generator issues a warning. When looking for a name described in a cref attribute, the documentation generator must respect namespace visibility according to using statements appearing within the source code.

The <summary> tag is intended to be used by a documentation viewer to display additional information about a type or member.

The <include> tag includes information from an external XML file.

Note carefully that the documentation file does not provide full information about the type and members (for example, it does not contain any type information). To get such information about a type or member, the documentation file must be used in conjunction with reflection on the actual type or member.

A.2

Recommended tags

The documentation generator must accept and process any tag that is valid according to the rules of XML. The following tags provide commonly used functionality in user documentation. (Of course, other tags are possible.)

Tag

Section

Purpose

<c>

‎A.2.1

Set text in a code-like font

<code>

‎A.2.2

Set one or more lines of source code or program output

<example>

‎A.2.3

Indicate an example

<exception>

‎A.2.4

Identifies the exceptions a method can throw

<include>

‎A.2.5

Includes XML from an external file

<list>

‎A.2.6

Create a list or table

<para>

‎A.2.7

Permit structure to be added to text

<param>

‎A.2.8

Describe a parameter for a method or constructor

<paramref>

‎A.2.9

Identify that a word is a parameter name

<permission>

‎A.2.10

Document the security accessibility of a member

<remarks>

‎A.2.11

Describe a type

<returns>

‎A.2.12

Describe the return value of a method

<see>

‎A.2.13

Specify a link

<seealso>

‎A.2.14

Generate a See Also entry

<summary>

‎A.2.15

Describe a member of a type

Copyright Microsoft Corporation 1999-2003. All Rights Reserved.335

Document info
Document views986
Page views986
Page last viewedFri Dec 09 04:57:15 UTC 2016
Pages396
Paragraphs9401
Words133190

Comments