X hits on this document





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.


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.)






Set text in a code-like font



Set one or more lines of source code or program output



Indicate an example



Identifies the exceptions a method can throw



Includes XML from an external file



Create a list or table



Permit structure to be added to text



Describe a parameter for a method or constructor



Identify that a word is a parameter name



Document the security accessibility of a member



Describe a type



Describe the return value of a method



Specify a link



Generate a See Also entry



Describe a member of a type

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

Document info
Document views519
Page views519
Page last viewedMon Oct 24 12:30:38 UTC 2016