C# 0 The Complete Reference

The XML Comment Tags

C# supports the XML documentation tags shown in Table A-1. Most of the XML comment 

tags are readily understandable, and they work like all other XML tags with which most 

programmers are already familiar. However, the 

 tag is more complicated than the 

others. A list contains two components: a list header and list items. The general form of a list 

header is shown here:

     

name

 

     

text

 

Here, 

text

 describes 

name.

 For a table, 

text

 is not used. The general form of a list item is 

shown next:

     

item-name

 

     

text

 

Here, 

text

 describes 

item-name.

 For bulleted or numbered lists or tables, 

item-name

 is not 

used. There can be multiple 

 entries.

867

APPENDIX

www.freepdf-books.com

---

868

 

P a r t   I I :  

E x p l o r i n g   t h e   C #   L i b r a r y

Compiling Documentation Comments

To produce an XML file that contains the documentation comments, specify the 

/doc

option.

For example, to compile a file called 

DocTest.cs

 that contains XML comments, use this 

command line:

csc DocTest.cs /doc:DocTest.xml

Tag

Description

code

Specifies the text specified by 

code

 as program code.



code

 

Specifies multiple lines of text specified by 

code

 as program code. 

explanation

 

The text associated with e

xplanation

 describes a code example.

name

”>

explanation

Describes an exception. The exception is specified by 

name.


‘fname’

 path = 

‘path

 [@

tagName = “tagID

 “]’ />

Specifies a file that contains the XML comments for the current 

file. The file is specified by 

fname.

 The path to the tag, the tag 

name, and the tag ID are specified by 

path, tagName,

 and 

tagID,

respectively.

type

””>

   list-header

   list-items

Specifies a list. The type of the list is specified by 

type,

 which must 

be either bullet, number, or table. 
text

 

Specifies a paragraph of text within another tag.

‘param

-

name’

>

explanation
Documents the parameter specified by 

param-name

. The text 

associated with e

xplanation

 describes the parameter.

param

-

name

” />

Specifies that 

param-name

 is a parameter name.

identifier

”>

explanation

Describes the permission setting associated with the class 

members specified by 

identifier.

 The text associated with 

e

xplanation

 describes the permission settings.

 

explanation

 

The text specified by 

explanation

 is a general commentar y often 

used to describe a type, such as a class or structure.

 

explanation

 

The text specified by explanation documents the return value of a 

method.

identifier

” />

Declares a link to another element specified by 

identifier.


identifier

” />

Declares a “see also” link to 

identifier.



 explanation

 

The text specified by 

explanation

 is a general commentar y often 

used to describe a method or other class member.


param

-

name

”>

explanation

Documents the type parameter specified by 

param-name.

 The text 

associated with e

xplanation

 describes the type parameter.

param

-

name

”/>

Specifies that 

param

-

name

 is the name of a type parameter.



explanation

 

The text specified by 

explanation

 documents a proper ty.

T

ABLE

 A-1 

The XML Comment Tags

www.freepdf-books.com

---

PART II

A p p e n d i x   A :  

D o c u m e n t a t i o n   C o m m e n t   Q u i c k   R e f e r e n c e    

869

To create an XML output file when using the Visual Studio 2008 IDE, you must activate 

the Properties page. Next, select Build. Then, check the XML Documentation File box and 

specify the name of the XML file.

An XML Documentation Example

Here is an example that demonstrates several documentation comments. It uses both the 

multiline and the single-line forms. As a point of interest, many programmers use a series of 

single-line documentation comments rather than a multiline comment even when a comment 

spans several lines. (Several of the comments in this example use this approach.) The advantage 

is that it clearly identifies each line in a longer documentation comment as being part of a 

documentation comment. This is, of course, a stylistic issue, but it is common practice.

// A documentation comment example.

using System;

/**

 This is an example of multiline XML documentation.

 The Test class demonstrates several tags.

*/

class Test {

  ///

  /// Main is where execution begins.

  ///

  static void Main() {

    int sum;

    sum = Summation(5);

    Console.WriteLine("Summation of " + 5 + " is " + sum);

  }

  ///

  /// Summation returns the summation of its argument.

  ///

  /// The value to be summed is passed in val.

  ///

  ///

  ///

  /// The summation is returned as an int value.

  ///

  ///

  static int Summation(int val) {

    int result = 0;

    for(int i=1; i <= val; i++)

      result += i;

    return result;

  }

}

www.freepdf-books.com

---

870

 

P a r t   I I :  

E x p l o r i n g   t h e   C #   L i b r a r y

Assuming the preceding program is called 

XmlTest.cs

, the following line will compile 

the program and produce a file called 

XmlTest.xml

 that contains the comments:

csc XmlTest.cs /doc:XmlTest.xml

After compiling, the following XML file is produced:

   

        DocTest

   

   

       

           

             This is an example of multiline XML documentation.

             The Test class demonstrates several tags.

           

       

       

           

            Main is where execution begins.

           

       

       

           

            Summation returns the summation of its argument.

           

            The value to be summed is passed in val.

           

           

           

            The summation is returned as an int value.

           

           

       

   

Notice that each documented element is given a unique identifier. These identifiers can be 

used by other programs that use the XML documentation.

www.freepdf-books.com

---

Index

Symbols

&

bitwise AND, 73–76

logical AND, 67, 68, 70, 71, 

229–235

pointer operator, 587

&& (short-circuit or conditional 

AND), 67, 70–71, 229, 231–235

*

multiplication operator, 24, 63

pointer operator, 586–587, 

594, 595

@ to designate verbatim string 

literals, 48–49

@ - qualified keywords, 33–34

|

bitwise OR, 73, 76–77

logical OR, 67, 68, 69–70, 71, 

229–235

|| (short-circuit or conditional OR), 

67, 70, 71, 229, 231–235

[ ], 137, 138, 142, 145, 151, 245, 483, 

484, 598

^

bitwise exclusive OR, 73, 77–78

logical exclusive OR, 67, 68

: (colon), 271, 278, 334

:: namespace alias qualifier, 447–451

{ }, 20, 21, 29, 31, 52, 118, 140, 143, 

414, 416, 569

used with format specifiers, 43–46

=, 24, 71–72

= = (relational operator), 27, 67, 537

overloading, 224, 226, 306

and strings, 158, 665

=> lambda operator, 413–414

!, 67, 68, 69–70, 229–231

!=, 27, 67, 537

overloading, 226

and strings, 158, 665

/, 24, 63

/* */, 20

/** */, 867

//, 21

///, 867

<

I/O redirection operator, 381–382

relational operator, 27, 67, 

224–226

<  >, 497

<<, 73, 79–81

<=, 27, 67, 226

–, 24, 63

– =

compound assignment 

operator, 72

and delegates, 404

and event accessors, 425

–>, 589

– –, 29, 63, 64–65

overloading, 217

%

modulus operator, 63–64

used with custom date and time 

placeholder characters, 698

( ), 21, 83, 116, 122

. (dot operator), 111, 119, 205, 332, 589

+

addition operator, 24, 63

concatenating strings with, 

159, 670

used with WriteLine( ), 24

+=

compound assignment 

operator, 72

and delegates, 404

and event accessors, 425

++, 29, 63, 64–67

overloading, 217–220

#

used with preprocessor 

directive, 451

used with WriteLine( ), 45, 

692–695

?

conditional operator, 82–83

used with nullable type 

declaration, 599

?? null coalescing operator, 601–602

>

I/O redirection operator, 381–382

relational operator, 27, 67, 

224–226

>>, 73, 79–81

>=, 27, 67, 226

; (semicolon), 21, 31, 92, 143, 409, 548

used in a custom format 

specifier, 693–694, 695

~

bitwise NOT, 73, 78–79

used in destructor declaration, 

131–132