(ZT)Introduction to GhostDoc

http://dotnetslackers.com/articles/vs_addin/Introduction_ghostdoc.aspx

 

Introduction

The XML documentation comments of C# reward you in multiple ways: Visual Studio shows their content on various occasions (e.g. in tooltips in the text editor, or in the object browser), and some tools (e.g. NDoc or Microsoft's documentation tool code-named Sandcastle) can generate nice looking help files for you. So overall, writing XML documentation comments sounds like a pretty good idea - unfortunately it often consists of a lot of stupid work that simply has to be done.

For example the documentation of constructors ("Initializes a new instance of <see cref="Foobar" />."), or properties (how often did you write "Gets or sets ..."? Or worse, "Gets or sets a value indicating whether..."?). Often enough you need the same documentation over and over again, e.g. when working with interfaces or class hierarchies.

What does GhostDoc do?

GhostDoc installs a new command for Visual Studio's C# source code editor. When editing a source file, you simply navigate the cursor into the method or property you want to document, call that command by pressing a hotkey (or using the context menu) and GhostDoc will insert an XML documentation comment. Much like typing "///" in front of the method or property, but instead of creating just an empty skeleton, GhostDoc tries to generate large parts of the actual documentation.

If your class member is an interface implementation or an override of a base class member, GhostDoc will use the existing documentation, regardless of where the interface or base class comes from. So basically what this means that you can re-use tons of documentation that Microsoft wrote - just remember the last time you've implemented IEnumerable and thought about how to comment the GetEnumerator() method.

In those cases where no existing documentation can be used, GhostDoc tries to guess the texts for the comments. While this idea seems to be a bit strange at first, under certain conditions (we'll get to that later) GhostDoc actually does a pretty good job. Often enough the results are not accurate or even downright funny, but on average correcting the mistakes/problems in the generated documentation takes less time than writing the whole comment from scratch.

But how can a tool with virtually no understanding of the English language generate often pretty accurate documentation? Well, the basic idea is pretty simple: GhostDoc assumes that your code follows the Microsoft's Design Guidelines for Class Library Developers:

• you are using PascalCasing or camelCasing to write identifier names consisting of multiple words
• your method names usually start with a verb
• you do not use abbreviations in identifier names

If you follow these rules (e.g. write "ClearCache()" instead of "Clrcch()") and choose more or less self-documenting identifier names, there's a good chance for GhostDoc to split the identifier names into words, tweak and/or shuffle them a little and produce a comment that, while not perfect, gives you a head start on the way to good documentation.

The text generation is performed using customizable rules and templates, and in addition to the built-in rules it is possible to define new custom rules that extend or replace existing rules (by giving the custom rules a higher priority and/or disabling built-in rules)

As mentioned above, GhostDoc does not really understand English identifier names, nevertheless it tries to apply certain mechanisms to increase the quality of the generated comments:

• Handling of verbs (GhostDoc assumes the first word of a method name to be a verb): Add -> Adds , Do -> Does, Specify -> Specifies
• "Of the" reordering (using trigger words like "width", "height", "name", etc.): ColumnWidth -> Width of the column
• Combined with special handling of specific adjectives: MaximumColumnWidth -> "Maximum width of the column" instead of "Width of the maximum column"
• Automatic detection of acronyms consisting of consonants (Html -> HTML), combined with a list-based approach for other acronyms (Gui -> GUI)
• Use of a list of words where that should not be headed by a "the" (AddItem -> Adds the item, but BuildFromScratch -> Builds from scratch)

Here are some examples of what GhostDoc can do:

/// <summary>
/// Appends the HTML text.
/// </summary>
/// <param name="htmlProvider">The HTML provider.</param>
public void AppendHtmlText( IHtmlProvider htmlProvider )

/// <summary>
/// Adds the specified item.
/// </summary>
/// <param name="item">The item.</param> 
public void Add( string item )

/// <summary>
/// Determines the size of the page buffer.
/// </summary>
/// <param name="initialPageBufferSize">Initial size of the page buffer.</param> 
/// <returns></returns> 
public int DeterminePageBufferSize( int initialPageBufferSize )

As the quality of the comment depends heavily on the quality of the identifier name, using GhostDoc for a longer period of time actually teaches writing consistent and self-documenting identifier names, which is definitely a nice side-effect.

What doesn't GhostDoc do?

GhostDoc cannot perform miracles, and the way it guesses documentation may not work well with your personal style. And GhostDoc is not a tool for creating the complete documentation for a given source file in one go. You can only document one member at a time - which is by design and fully intentional, because you always have to check and, if necessary, correct the results of each text generation.

Summary

GhostDoc is a free add-in for Visual Studio that automatically generates XML documentation comments. Either by using existing documentation inherited from base classes or implemented interfaces, or by deducing comments from name and type of e.g. methods, properties or parameters.

References

GhostDoc can be downloaded from the GhostDoc website:
http://www.roland-weigelt.de/ghostdoc