Visual Studio Hacks

276

|

Chapter 8, Comments and Documentation

#68 Master C# XML Comments

HACK

<seealso>. The <seealso> tag can be used to reference other classes or docu-

ments that might be of interest to the person reading the documentation.

You can include any number of

<seealso> tags that point to other types or

type members. Here is an example of the

<seealso> tag:

/// <summary>

/// This method retrieves the owner of this vehicle

/// </summary>

/// <returns>The userID of the vehicle's owner</returns>

/// <seealso cref="SetOwner"/>

public int GetOwnerID( )

Using the <seealso> tag, you can reference other types, methods, properties,

or fields that might be of interest to the user.

<include>. The

<include> tag is different then the other primary tags

because it is used to include outside XML comments, as opposed to docu-

menting anything. The

<include> tag can be useful if the XML comments in

your source files are becoming increasingly large and unwieldy. To use this

tag, you will need to specify the name of the file as well as the XPath expres-

sion that should be used to get to your comments. The best way to handle

this is to create a file that reproduces the file generated by Visual Studio—

you can even let Visual Studio create this file for you and then replace your

comments with

<include> statements. Here is an example of an <include>

statement that would use the generated file (see the “Creating the XML File”

section ...