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.

Get Visual Studio Hacks now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.