Published: 30 Oct 2006
By: Roland Weigelt

GhostDoc is a free add-in for Visual Studio that helps developers writing XML documentation comments.

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:

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

Continue reading and see our next or previous articles Next Article >>

About Roland Weigelt

Sorry, no bio is available

View complete profile here.

Other articles in this category


Lessons learned from Copy to Html Add-in
This article contains some lessons learned from creating an add-in for Visual Studio 2005 that adde...
Book Review: Professional Visual Studio Extensibility
Review of the book: Professional Visual Studio Extensibility.

You might also be interested in the following related blog posts


New article: How to detect and avoid memory and resources leaks in .NET applications read more
Upgrading from Weigelt GhostDoc to SubMain GhostDoc read more
The Future of GhostDoc read more
Time Flys Like An Arrow; Fruit Flies Like A Banana read more
Back to Basics: Delegates, Anonymous Methods and Lambda Expressions read more
Code readability - Documentation vs. Refactoring read more
.NET Coding Guidelines read more
Review: Professional ASP.NET 2.0 Ajax read more
GhostDoc News read more
GhostDoc in "Windows Developer Power Tools" read more
Top
 
 
 

Please login to rate or to leave a comment.