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