Visual Studio Hacks

Create Comments Faster #69

Chapter 8, Comments and Documentation

|

281

HACK

/// <summary>

///

/// </summary>

/// <param name="htmlProvider"></param>

public void AppendHtmlText(HtmlProvider htmlProvider)

{

...

}

You would then add your text, so the XML documentation comment could,

for example, look something like this:

/// <summary>

/// Appends the HTML text of the specified provider.

/// </summary>

/// <param name="htmlProvider">The HTML provider.</param>

public void AppendHtmlText(HtmlProvider htmlProvider)

{

...

}

This is a typical method that comes by the dozen: the method name pretty

much says what it is doing and you definitely do not need much imagina-

tion to write the comment—after some time, these methods become a real

drain to document. On the other hand, you simply have no choice. If you

want the benefits of XML documentation comments (perhaps a nice help

file generated by NDoc

[Hack #71]), you have to comment all public (and pro-

tected) members, period.

Let’s take a closer look at the earlier example. The method is written accord-

ing to Microsoft’s Design Guidelines for Class Library Developers; some of

these rules are:

• Identifier names consisting of multiple words are written in Pascal-

Casing (the method name) or camelCasing (the parameter name).

• Acronyms are treated like normal words and are formatted accordingly

(for example, “Html” instead of “HTML”).

• Identifier names do not contain abbreviations.

• Method names usually start with a verb.

Now when you look at this set of rules on one hand and the documentation

you have written on the other, it is pretty safe to say that a large part of the

documentation could have been generated automatically.

GhostDoc

GhostDoc is an add-in for Visual Studio .NET 2003 that tries to do just that.

With GhostDoc installed, you move the cursor into the method or property

282

|

Chapter 8, Comments and Documentation

#69 Create Comments Faster

HACK

you want to document, invoke the Document This command using either

the source editor’s context (right-click) menu or a hotkey, and GhostDoc

will create an XML documentation comment. The result for the previous

example would be:

/// <summary>

/// Appends the HTML text.

/// </summary>

/// <param name="htmlProvider">The HTML provider.</param>

public void AppendHtmlText(HtmlProvider htmlProvider)

{

...

}

Pretty close—but how does GhostDoc do that? First of all, it’s important to

note that the add-in has no idea of what the identifiers actually mean—

GhostDoc simply assumes that the code is written according to the guide-

lines and does the following:

• It breaks up identifier names into single words by analyzing the casing.

• A word consisting of only consonants (for example, “HTML”) is auto-

matically treated as an abbreviation (other abbreviations, for example,

“UML,” can be specified explicitly).

• For methods, the first word is treated as a verb and thus an s (in some

cases es) is added.

• A “the” is added between the first and the second word of the method

name (unless the second word belongs to a configurable list of words

that are never preceded by a “the”).

After GhostDoc has created the XML documentation comment, the devel-

oper has to edit only a few details (for example, for the

AppendHtmlText

method, add “using the specified provider” to the end of the sentence)

before moving on to the really interesting part of the documentation:

remarks on usage, references to related methods or properties, example

code—information that cannot be created automatically.

GhostDoc is driven by generation rules. When an XML documentation com-

ment is about to be generated, the add-in will collect information about the

code element (method, property, indexer, etc.) like name, return type, param-

eter names and types, and so on. This information is then compared to a set of

rules, and the rule that fits best is then used to generate the documentation.

With each version of GhostDoc, the number of rules grows; the more spe-

cialized they are (for example, rules for handling Boolean properties, meth-

ods with a name consisting of only one word, etc.), the better the results.