Annex E Documentation Comments

1Annex E. Documentation Comments

2This annex is informative.

3C# provides a mechanism for programmers to document their code using a special comment syntax that

4contains XML text. Comments using such syntax are called documentation comments. The XML

5generation tool is called the documentation generator. (This generator could be, but need not be, the

6C# compiler itself.) The output produced by the documentation generator is called the documentation file. A

7documentation file is used as input to a documentation viewer; a tool intended to produce some sort of

8visual display of type information and its associated documentation.

9A conforming C# compiler is not required to check the syntax of documentation comments; such comments

10are simply ordinary comments. A conforming compiler is permitted to do such checking, however.

11This specification suggests a set of standard tags to be used in documentation comments. For

12C# implementations targeting the CLI, it also provides information about the documentation generator and

13the format of the documentation file. No information is provided about the documentation viewer.

14E.1 Introduction

15Comments having a special form can be used to direct a tool to produce XML from those comments and the

16source code elements, which they precede. Such comments are single-line comments of the form /// … or

17delimited comments of the form /** … */. They must immediately precede a user-defined type (such as a

18class, delegate, or interface) or a member (such as a field, event, property, or method) that they annotate.

19Syntax:

20single-line-doc-comment::

21/// input-charactersopt

22delimited-doc-comment::

23/** delimited-comment-charactersopt */

24In a single-line-doc-comment, if there is a whitespace character following the /// characters on each of the

25single-line-doc-comments adjacent to the current single-line-doc-comment, then that whitespace character is

26not included in the XML output.

27In a delimited-doc-comment, if the first non-whitespace character on the second line is an asterisk and the

28same pattern of optional whitespace characters and an asterisk character is repeated at the beginning of each

29of the lines within the delimited-doc-comment, then the characters of the repeated pattern are not included in

30the XML output. The pattern can include whitespace characters after, as well as before, the asterisk

31character.

32Example:

33/**

34* <remarks>

35* Class <c>Point</c> models a point in a two-dimensional plane.

36* </remarks>

37*/

38public class Point

39{

41void Draw() { … }

42}

511