第 35 页

shortcut code /// in C# before a member or class declaration. In some cases the XML comments

will already be present in code generated by the supplied project templates, as shown in Figure 12-1.

fiGure 12-1

The automatic insertion of the summary section can be enabled or disabled in

the Visual Studio options. Select Tools . Options, and then choose Text

Editor . C# . Advanced from the navigation tree. Uncheck the “Generate

XML documentation comments for ///” option to disable this feature.

Adding an XML comment block to VB is achieved by using the ‘'’ shortcut code. In this way it

replicates the way C# documentation is generated.

In both languages, once the comments have been added, Visual Studio automatically adds a

collapsible region to the left margin so you can hide the documentation when you’re busy writing

code. Hovering over the collapsed area displays a tooltip message containing the first few lines of

the comment block.

222 .

chaPter 12 documenTATion WiTh xml commenTS

xMl comment tags

Though you can use any kind of XML comment structure you like, including your own custom

XML tags, Visual Studio’s XML comment processor recognizes a number of predefined tags and

automatically formats them appropriately. The Sandcastle document compiler, which is discussed

later in this chapter, has support for a number of additional tags, and you can supplement these

further with your own XML schema document.

If you need to use angle brackets in the text of a documentation comment, use

the entity references & lt; and & gt;.

Because documentation is so important, the next section of this chapter details each of these

predefined tags, their syntax, and how you would use them in your own documentation.

The <c> Tag

The

tag indicates that the enclosed text should be formatted as code, rather than normal text. >c<

It’s used for code that is included in a normal text block. The structure of

is simple, with any >c<

text appearing between the opening and closing tags being marked for formatting in the code style.

<c > code-formatted text < /c >

The following example shows how

c#

/// <summary>

might be used in the description of a property: >c<

/// The <c>UserId</c> property is used in conjunction with other properties

/// to setup a user properly. Remember to set the <c>Password</c> field too.

/// </summary>

public string UserId { get; set; }

Vb

‘’’ <summary>

‘’’ The <c>UserId</c> property is used in conjunction with other properties

‘’’ to setup a user properly. Remember to set the <c>Password</c> field too.

‘’’ </summary>

Public Property UserId() As String

The <code> Tag

If the amount of text in the documentation you need to format as code is more than just a

phrase within a normal text block, you can use the < code > tag instead of

. This tag marks >c<

everything within it as code, but it’s a block-level tag, rather than a character-level tag. The syntax

of this tag is a simple opening and closing tag with the text to be formatted inside, as shown here:

XMl Comments .

223

<code>

Code-formatted text

Code-formatted text

</code>

The <code> tag can be embedded inside any other XML comment tag. The following code shows an

example of how it could be used in the summary section of a property definition:

c#

/// <summary>

/// The <c>UserId</c> property is used in conjunction with other properties

/// to setup a user properly. Remember to set the <c>Password</c> field too.

/// For example:

/// <code>

/// myUser.UserId = "daveg"

/// myUser.Password = "xg4*Wv"

/// </code>

/// </summary>

public string UserId { get; set; }

Vb

''' <summary>

''' The <c>UserId</c> property is used in conjunction with other properties

''' to setup a user properly. Remember to set the <c>Password</c> field too.

''' For example:

''' <code>

''' myUser.UserId = "daveg"

''' myUser.Password = "xg4*Wv"

''' </code>

''' </summary>

Public Property UserId() As String

The <example> Tag

A common requirement for internal documentation is to provide an example of how a particular

procedure or member can be used. The <example> tags indicate that the enclosed block should be

treated as a discrete section of the documentation, dealing with a sample for the associated member.

Effectively, this doesn’t do anything more than help organize the documentation, but used in

conjunction with an appropriately designed XML style sheet or processing instructions, the example

can be formatted properly.

The other XML comment tags, such as <c> and <code>, can be included in the text inside the

<example> tags to give you a comprehensively documented sample. The syntax of this block-level

tag is simple:

<example>

Any sample text goes here.

</example>

224 .

chaPter 12 documenTATion WiTh xml commenTS

Using the example from the previous discussion, the following code moves the <code> formatted

text out of the <summary> section into an <example> section:

c#

/// <summary>

/// The <c>UserId</c> property is used in conjunction with other properties

/// to setup a user properly. Remember to set the <c>Password</c> field too.

/// </summary>

/// <example>

/// <code>

/// myUser.UserId = "daveg"

/// myUser.Password = "xg4*Wv"

/// </code>

/// </example>

public string UserId { get; set; }

Vb

''' <summary>

''' The <c>UserId</c> property is used in conjunction with other properties

''' to setup a user properly. Remember to set the <c>Password</c> field too.

''' </summary>

''' <example>

''' <code>

''' myUser.UserId = "daveg"

''' myUser.Password = "xg4*Wv"

''' </code>

''' </example>

Public Property UserId() As String

The <exception> Tag

The <exception> tag is used to define any exceptions that could be thrown from within the

member associated with the current block of XML documentation. Each exception that can be

thrown should be defined with its own <exception> block, with an attribute of cref identifying

the fully qualified type name of an exception that could be thrown. Note that the Visual Studio

2010 XML comment processor checks the syntax of the exception block to enforce the inclusion

of this attribute. It also ensures that you don’t have multiple <exception> blocks with the same

attribute value. The full syntax is as follows:

<exception cref="exceptionName">

Exception description.

</exception>

Extending the examples from the previous tag discussions, the following code adds two

exception definitions to the XML comments associated with the UserId property: System.

TimeoutException, and System.UnauthorizedAccessException.

c#

/// <summary>

/// The <c>UserId</c> property is used in conjunction with other properties

/// to setup a user properly. Remember to set the <c>Password</c> field too.

XMl Comments .

225

/// </summary>

/// <exception cref="System.TimeoutException">

/// Thrown when the code cannot determine if the user is valid within a reasonable

/// amount of time.

/// </exception>

/// <exception cref="System.UnauthorizedAccessException">

/// Thrown when the user identifier is not valid within the current context.

/// </exception>

/// <example>

/// <code>

/// myUser.UserId = "daveg"

/// myUser.Password = "xg4*Wv"

/// </code>

/// </example>

public string UserId { get; set; }

Vb

''' <summary>

''' The <c>UserId</c> property is used in conjunction with other properties

''' to setup a user properly. Remember to set the <c>Password</c> field too.

''' </summary>

''' <exception cref="System.TimeoutException">

''' Thrown when the code cannot determine if the user is valid within a reasonable

''' amount of time.

''' </exception>

''' <exception cref="System.UnauthorizedAccessException">

''' Thrown when the user identifier is not valid within the current context.

''' </exception>

''' <example>

''' <code>

''' myUser.UserId = "daveg"

''' myUser.Password = "xg4*Wv"

''' </code>

''' </example>

Public Property UserId() As String

The <include> Tag

You’ll often have documentation that needs to be shared across multiple projects. In other

situations, one person may be responsible for the documentation while others are doing the

coding. Either way, the <include> tag will prove useful. The <include> tag enables you to refer to

comments in a separate XML file so they are brought inline with the rest of your documentation.

Using this method, you can move the actual documentation out of the code, which can be handy

when the comments are extensive.

The syntax of <include> requires that you specify which part of the external file is to be used in the

current context. The path attribute is used to identify the path to the XML node, and uses standard

XPath terminology:

<include file="filename" path="XPathQuery" />

226 .

chaPter 12 documenTATion WiTh xml commenTS

The external XML file containing the additional documentation must have a path that can be

navigated with the attribute you specify, with the end node containing an attribute of name to

uniquely identify the specific section of the XML document to be included.

You can include files in either VB or C# using the same tag. The following code takes the samples

used in the <exception> tag discussion and moves the documentation to an external file:

c#

/// <include file="externalFile.xml" path="MyDoc/Properties[@name='UserId']/*" />

public string UserId { get; set; }

Vb

''' <include file="externalFile.xml" path="MyDoc/Properties[@name='UserId']/*" />

Public Property UserId() As String

The external file’s contents would be populated with the following XML document structure to

synchronize it with what the <include> tag processing expects to find:

<MyDoc>

<Properties name="UserId">

<summary>

The <c>sender</c> object is used to identify who invoked the procedure.

</summary>

<summary>

The <c>UserId</c> property is used in conjunction with other properties

to setup a user properly. Remember to set the <c>Password</c> field too.

</summary>

<exception cref="System.TimeoutException">

Thrown when the code cannot determine if the user is valid within a

reasonable amount of time.

</exception>

<exception cref="System.UnauthorizedAccessException">

Thrown when the user identifier is not valid within the current context.

</exception>

<example>

<code>

myUser.UserId = "daveg"

myUser.Password = "xg4*Wv"

</code>

</example>

</Procedures>

</MyDoc>

The <list> Tag

Some documentation requires lists of various descriptions, and with the <list> tag you can

generate numbered and unnumbered lists along with two-column tables. All three take two

parameters for each entry in the list — a term and a description — represented by individual XML

tags, but they instruct the processor to generate the documentation in different ways.

XMl Comments .

227

To create a list in the documentation, use the following syntax, where type can be one of the

following values — bullet, numbered, or table:

<list type="type">

<listheader>

<term>termName</term>

<description>description</description>

</listheader>

<item>

<term>myTerm</term>

<description>myDescription</description>

</item>

</list>

The <listheader> block is optional, and is usually used for table-formatted lists or definition lists.

For definition lists, the <term> tag must be included, but for bullet lists, numbered lists, or tables

the <term> tag can be omitted.

The XML for each type of list can be formatted differently using an XML style sheet. An example

of how to use the <list> tag appears in the following code. Note how the sample has omitted the

listheader tag, because it was unnecessary for the bullet list:

c#

/// <summary>

/// This function changes a users password. The password change could fail for

/// several reasons:

/// <list type="bullet">

/// <item>

/// <term>Too Short</term>

/// <description>The new password was not long enough.</description>

/// </item>