C# Language Specification

Introduction

Comments having a special form can be used to direct a tool to produce XML from those comments and the source code elements, which they precede. Such comments are single-line comments that start with three slashes (///), or delimited comments that start with a slash and two stars (/**). They must immediately precede a user-defined type (such as a class, delegate, or interface) or a member (such as a field, event, property, or method) that they annotate. Attribute sections (§17.2) are considered part of declarations, so documentation comments must precede attributes applied to a type or member.

Syntax:

single-line-doc-comment:
/// input-characters_opt

delimited-doc-comment:
/** delimited-comment-text_opt */

In a single-line-doc-comment, if there is a whitespace character following the /// characters on each of the single-line-doc-comments adjacent to the current single-line-doc-comment, then that whitespace character is not included in the XML output.

In a delimited-doc-comment, if the first non-whitespace character on the second line is an asterisk and the same pattern of optional whitespace characters and an asterisk character is repeated at the beginning of each of the line within the delimited-doc-comment, then the characters of the repeated pattern are not included in the XML output. The pattern may include whitespace characters after, as well as before, the asterisk character.

Example:

///

Class Point models a point in a two-dimensional

/// plane.

///
public class Point
{
///

method draw renders the point.

void draw() {…}
}

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 §C. Some of the recommended tags have special meanings:

• 
  The
  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. For code elements that are generic, the normal generic syntax (ie “List”) cannot be used because it produces invalid XML. Braces can be used instead of brackets (ie “List{T}”), or the XML escape syntax can be used (ie “List<T>”).
  
• 
  The
  tag is intended to be used by a documentation viewer to display additional information about a type or member.
  

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

3.