C# LANGUAGE SPECIFICATION

1The text within documentation comments must be well formed according to the rules of XML

2(http://www.w3.org/TR/REC-xml). If the XML is ill formed, a warning is generated and the documentation

3file will contain a comment saying that an error was encountered.

4Although developers are free to create their own set of tags, a recommended set is defined in §E.2. Some of

5the recommended tags have special meanings:

6• The <param> tag is used to describe parameters. If such a tag is used, the documentation generator must

7verify that the specified parameter exists and that all parameters are described in documentation

8comments. If such verification fails, the documentation generator issues a warning.

9• The cref attribute can be attached to any tag to provide a reference to a code element. The

10documentation generator must verify that this code element exists. If the verification fails, the

11documentation generator issues a warning. When looking for a name described in a cref attribute, the

12documentation generator must respect namespace visibility according to using statements appearing

13within the source code.

14• The <summary> tag is intended to be used by a documentation viewer to display additional information

15about a type or member.

16Note carefully that the documentation file does not provide full information about the type and members (for

17example, it does not contain any type information). To get such information about a type or member, the

18documentation file must be used in conjunction with reflection on the actual type or member.

19E.2 Recommended tags

20The documentation generator must accept and process any tag that is valid according to the rules of XML.

21The following tags provide commonly used functionality in user documentation. (Of course, other tags are

22possible.)

23

24

512

Annex E Documentation Comments

1E.2.1 <c>

2This tag provides a mechanism to indicate that a fragment of text within a description should be set in a

3special font such as that used for a block of code. For lines of actual code, use <code> (§E.2.2).

4Syntax:

5<c>text to be set like code</c>

6Example:

7/// <remarks>

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

9/// </remarks>

10public class Point

11{

12…

13}

14E.2.2 <code>

15This tag is used to set one or more lines of source code or program output in some special font. For small

16code fragments in narrative, use <c> (§E.2.1).

17Syntax:

18<code>source code or program output</code>

19Example:

20/// <summary>

21/// Changes the Point's location by the given x- and y-offsets.

22/// </summary>

23/// <example>

24/// The following code:

29/// results in <c>p</c>'s having the value (2,8).

30/// </example>

31public void Translate(int xor, int yor) {

33Y += yor;

34}

35E.2.3 <example>

36This tag allows example code within a comment, to specify how a method or other library member might be

37used. Ordinarily, this would also involve use of the tag <code> (§E.2.2) as well.

38Syntax:

39<example>description</example>

40Example:

41See <code> (§E.2.2) for an example.

42E.2.4 <exception>

43This tag provides a way to document the exceptions a method can throw.

44Syntax:

45<exception cref="member">description</exception>

46where

47cref="member"

513

C# LANGUAGE SPECIFICATION

1The name of a member. The documentation generator checks that the given member exists and

2translates member to the canonical element name in the documentation file.

3description

4A description of the circumstances in which the exception is thrown.

5Example:

6public class DataBaseOperations

7{

16}

17}

18E.2.5 <list>

19This tag is used to create a list or table of items. It can contain a <listheader> block to define the heading

20row of either a table or definition list. (When defining a table, only an entry for term in the heading need be

21supplied.)

22Each item in the list is specified with an <item> block. When creating a definition list, both term and

23description must be specified. However, for a table, bulleted list, or numbered list, only description

24need be specified.

25Syntax:

26<list type="style">

39</item>

40</list>

41where

42style

43The style of the list. Must be bullet, number, or table.

44term

45The term to define, whose definition is in description.

46description

47Either an item in a bullet or numbered list, or the definition of a term.

48Example:

514

Annex E Documentation Comments

1public class MyClass

2{

16}

17}

18E.2.6 <para>

19This tag is for use inside other tags, such as <remarks> (§E.2.10) or <returns> (§E.2.11), and permits

20structure to be added to text.

21Syntax:

22<para>content</para>

23where

24content

25The text of the paragraph.

26Example:

27/// <summary>

32/// This program tests each method and operator, and is intended

33/// to be run after any non-trvial maintenance has been performed

34/// on the Point class.

35 /// </para>

36/// </summary>

37public static void Main() {

38…

39}

40E.2.7 <param>

41This tag is used to describe a parameter for a method, constructor, or indexer.

42Syntax:

43<param name="name">description</param>

44where

45name

46The name of the parameter.

47description

48A description of the parameter.

49Example:

515