第 37 页

''' <typeparam name="T">

''' Base item type (must implement IComparable)

''' </typeparam>

Public Class myList(Of T As IComparable)

'...code...

End Class

The <typeparamref> Tag

If you are referring to a generic type parameter elsewhere in the documentation other than the

<typeparam> tag, you can use the <typeparamref> tag to format the value, or even link to

the parameter information depending on how you code the XML transformation.

<typeparamref name="parameterName" />

Normally, <typeparamref> tags are used when you are referring to parameters in the larger

sections of documentation such as the <summary> or <remarks> tags, as the following code

demonstrates:

c#

/// <summary>

/// Creates a new list of arbitrary type <typeparamref name="T"/>

/// </summary>

/// <typeparam name="T">

/// Base item type (must implement IComparable)

/// </typeparam>

public class myList<T> where T : IComparable

{

//...code...

}

Vb

''' <summary>

''' Creates a new list of arbitrary type <typeparamref name="T"/>

''' </summary>

''' <typeparam name="T">

''' Base item type (must implement IComparable)

''' </typeparam>

Using XMl Comments .

235

Public Class myList(Of T As IComparable)

'...code...

End Class

The <value> Tag

Normally used to define a property’s purpose, the <value> tag gives you another section in the

XML where you can provide information about the associated member. The <value> tag is not

used by IntelliSense.

<value>The text to display</value>

When used in conjunction with a property, you would normally use the <summary> tag to describe

what the property is for, whereas the <value> tag is used to describe what the property represents:

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>

/// <value>

/// A string containing the UserId for the current user

/// </value>

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>

''' <value>

''' A string containing the UserId for the current user

''' </value>

Public Property UserId() As String

usinG xMl coMMents

Once you have the XML comments inline with your code, you’ll most likely want to generate an

XML file containing the documentation. In VB this setting is on by default, with an output path

and filename specified with default values. However, C# has the option turned off as its default

behavior, so if you want documentation you’ll need to turn it on manually.

To ensure that your documentation is being generated where you require, open the property pages

for the project through the Solution Explorer’s right-click context menu. Locate the project for

which you want documentation, right-click its entry in the Solution Explorer, and select Properties.

The XML documentation options are located in the Build section (see Figure 12-2). Below

the general build options is an Output section that contains a checkbox that enables XML

236 .

chaPter 12 documenTATion WiTh xml commenTS

documentation file generation. When this checkbox is checked, the text field next to it becomes

available for you to specify the filename for the XML file that will be generated.

fiGure 12-2

For VB applications, the option to generate an XML documentation file is on the Compile tab of the

project properties.

Once you’ve saved these options, the next time you perform a build, Visual Studio adds the /doc

compiler option to the process so that the XML documentation is generated as specified.

Generating an XML documentation file will slow down the compile time. If this

is impacting your development or debugging cycle, you can disable it for the

Debug build while leaving it enabled for the Release build.

The XML file that is generated will contain a full XML document that you can apply XSL

transformations against, or process through another application using the XML document object

model. All references to exceptions, parameters, methods, and other “see also” links will be

included as fully addressed information, including namespace, application, and class data. Later in

this chapter you see how you can make use of this XML file to produce professional-looking

documentation using Sandcastle.

Generating Documentation with GhostDoc .

237

intellisense information

The other useful advantage of using XML comments is how Visual Studio consumes them in

its own IntelliSense engine. As soon as you define the documentation tags that Visual Studio

understands, it will generate the information into its IntelliSense, which means you can refer to the

information elsewhere in your code.

You can access IntelliSense in two ways. If the member referred to is within the same project or is in

another project within the same solution, you can access the information without having to build or

generate the XML file. However, you can still take advantage of IntelliSense even when the project

is external to your current application solution.

The trick is to ensure that when the XML file is generated by the build process, it must have

the same name as the .NET assembly being built. For example, if the compiled output is

MyApplication.exe, the associated XML file should be named MyApplication.xml. In addition,

this generated XML file should be in the same folder as the compiled assembly so that Visual Studio

can locate it.

GeneratinG docuMentation with Ghostdoc

Although most developers will agree that documentation is important, it still takes a lot of time

and commitment to write. The golden rule of “if it’s easy the developer will have more inclination

to do it” means that any additional enhancements to the documentation side of development will

encourage more developers to embrace it.

You can always take a more authoritarian approach to documentation and use a

source code analysis tool such as StyleCop to enforce a minimum level of

documentation. StyleCop ships with almost 50 built-in rules specifically for

verifying the content and formatting of XML documentation. StyleCop is

discussed in more detail in chapter 13.

GhostDoc is an add-in for Visual Studio that attempts to do just that, providing the capability to set

up a keyboard shortcut that automatically inserts the XML comment block for a class or member.

However, the true power of GhostDoc is not in the capability to create the basic stub, but to

automate a good part of the documentation itself.

Through a series of lists that customize how different parts of member and variable names

should be interpreted, GhostDoc generates simple phrases that get you started in creating your

own documentation. For example, consider the list shown in Figure 12-3, where words are

defined as trigger points for “Of the” phrases. Whenever a variable or member name has the

string “color” as part of its name, GhostDoc attempts to create a phrase that can be used in

the XML documentation.

238 .

chaPter 12 documenTATion WiTh xml commenTS

fiGure 12-3

For instance, a property called NewBackgroundColor will generate a complete phrase of New color

of the background. The functionality of GhostDoc also recognizes common parameter names

and their purpose. Figure 12-4 shows this in action with a default Click event handler for a button

control. The sender and e parameters were recognized as particular types in the context of an event

handler, and the documentation that was generated by GhostDoc reflects this accordingly.

fiGure 12-4

GhostDoc is an excellent resource for those who find documentation difficult. You can find it at its

official web site, http://submain.com/ghostdoc.

coMPilinG docuMentation with sandcastle

Sandcastle is a set of tools published by Microsoft that act as documentation compilers. These

tools can be used to easily create very professional-looking external documentation in Microsoft

compiled HTML help (.chm) or Microsoft Help 2 (.hsx) format.

The primary location for information on Sandcastle is the Sandcastle blog at http://blogs.msdn.

com/sandcastle/ . There is also a project on CodePlex, Microsoft ’ s open source project hosting

site, at http://sandcastle.codeplex.com/ . You can fi nd documentation, a discussion forum, and

a link to download the latest Sandcastle installer package on this site.

By default, Sandcastle installs to c:\Program Files\Sandcastle . When it is run, Sandcastle

creates a large number of working fi les and the fi nal output fi le under this directory. Unfortunately

all fi les and folders under Program Files require administrator permissions to write to, which can

be problematic particularly if you are running on Windows Vista with UAC enabled. Therefore it is

recommended that you install it to a location where your user account has write permissions.

Out of the box, Sandcastle is used from the command line only. A number of third - parties have put

together GUI interfaces for Sandcastle, which are linked to on the Wiki.

To begin, open a Visual Studio 2010 Command Prompt from Start Menu . All Programs .

Microsoft Visual Studio 2010 . Visual Studio Tools, and change directory to < Sandcastle

Install Directory > \Examples\sandcastle\ .

The Visual Studio 2010 Command Prompt is equivalent to a normal command

prompt except that it also sets various environment variables, such as

directory search paths, which are often required by the Visual Studio 2010

command - line tools.

In this directory you will fi nd an example class fi le, test.cs, and an MSBuild project fi le,

build.proj. The example class fi le contains methods and properties that are commented with the

standard XML comment tags that were explained earlier in this chapter, as well as some additional

Sandcastle - specifi c XML comment tags. You can compile the class fi le and generate the XML

documentation fi le by entering the following command:

csc /t:library test.cs /doc:example.xml

Once that has completed, you are now ready to generate the documentation help fi le. The simplest

way to do this is to execute the example MSBuild project fi le that ships with Sandcastle. This project

fi le has been hard - coded to generate the documentation using test.dll and example.xml. Run the

MSBuild project by entering the following command:

msbuild build.proj

The MSBuild project will call several Sandcastle tools to build the documentation fi le including

MRefBuilder, BuildAssembler, and XslTransform.

Rather than manually running Sandcastle every time you build a release version,

it would be better to ensure that it is always run by executing it as a post - build

event. Chapter 6 describes how to create a build event.

Compiling Documentation with sandcastle . 239

240 .

chaPter 12 documenTATion WiTh xml commenTS

You may be surprised at how long the documentation takes to generate. This is partly because the

MRefBuilder tool uses reflection to inspect the assembly and all dependant assemblies to obtain

information about all of the types, properties, and methods in the assembly and all dependant

assemblies. In addition, anytime it comes across a base .NET Framework type, it will attempt to

resolve it to the MSDN online documentation in order to generate the correct hyperlinks in the

documentation help file.

The first time you run the MSBuild project, it generates reflection data for all of

the .NET Framework classes, so you can expect it to take even longer to complete.

By default, the build.proj MSBuild project generates the documentation with the vs2005 look-

and- feel, as shown in Figure 12-4, in the directory < Sandcastle Install Directory > \Examples\

sandcastle\chm\. You can choose a different output style by adding one of the following options

to the command line:

/property:PresentationStyle=vs2005

/property:PresentationStyle=hana

/property:PresentationStyle=prototype

fiGure 12-5

The following code shows the source code section from the example class fi le, test.cs , which

relates to the page of the help documentation shown in Figure 12 - 5.

/// < summary >

/// Swap data of type < typeparamref name="T"/ >

/// < /summary >

/// < param name="lhs" > left < typeparamref name="T"/ > to swap < /param >

/// < param name="rhs" > right < typeparamref name="T"/ > to swap < /param >

/// < typeparam name="T" > The element type to swap < /typeparam >

public void Swap < T > (ref T lhs, ref T rhs)

{

T temp;

temp = lhs;

lhs = rhs;

rhs = temp;

}

The default target for the build.proj MSBuild project is “ Chm, ” which builds a CHM compiled

HTML Help fi le for the test.dll assembly. You can also specify one of the following targets on the

command line:

/target:Clean - removes all generated files

/target:HxS - builds HxS file for Visual Studio in addition to CHM

The Microsoft Help 2 (.HxS) is the format that the Visual Studio help system

uses. You must install the Microsoft Help 2.x SDK in order to generate .HxS

fi les. This is available and included as part of the Visual Studio 2010 SDK.

task list coMMents

The Task List window is a feature of Visual Studio 2010 that allows you to keep track of any coding