Day: August 23, 2008

 

I have been using Roland WeigeIt’s GhostDoc 2.1.3 for both Visual Studio 2005 and 2008 for about six months, and I am hooked. For those of you who have not heard of GhostDoc, here is the summary from Roland’s site:

GhostDoc is a free add-in for Visual Studio that automatically generates XML documentation comments for C#. 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.

It saves me so much time writing XML documentation in my code that there is no longer any excuse for any docs being missing. Documenting a piece of code is as simple as right-clicking on it and selcting ‘Document This’ (there is also a keyboard shortcut – CTRL-D is the default). The built-in rules for creating the comments are probably sufficient for most developers, but more advanced users can edit existing rules or add their own.

I have attached a small sample project containing some domain classes representing part of a pharmacy system. Here are a few examples of the XML documentation that is generated using GhostDoc’s default configuration. Some of the code is a bit contrived so that I could demonstrate different types of comments.

Documenting a Constructor

/// <summary>
/// Initializes a new instance of the <see cref="Drug"/> class.
/// </summary>
/// <param name="id">The id.</param>
public Drug(int id)
{
    LoadDrug(id);
}

Documenting a Dispose Method

/// <summary>
/// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
/// </summary>
public void Dispose()
{
    // TODO: clean up resources
}

 

Documenting Properties

/// <summary>
/// Gets or sets the therapeutic categories.
/// </summary>
/// <value>The therapeutic categories.</value>
public List<DrugCategory> TherapeuticCategories { get; set; }

/// <summary>
/// Gets or sets the NDC.
/// </summary>
/// <value>The NDC.</value>
public string NDC { get; set; }

/// <summary>
/// Gets or sets a value indicating whether this instance is generic.
/// </summary>
/// <value>
///     <c>true</c> if this instance is generic; otherwise, <c>false</c>.
/// </value>
public bool IsGeneric { get; set; }

 

Documenting a Method

/// <summary>
/// Loads the drug.
/// </summary>
/// <param name="id">The id.</param>
private void LoadDrug(int id)
{
    // do nothing... just an example
}

 

Documenting an Inherited/Implemented Method

/// <summary>
/// Creates a new object that is a copy of the current instance.
/// </summary>
/// <returns>
/// A new object that is a copy of this instance.
/// </returns>
public object Clone()
{
    return MemberwiseClone();
}

 

Documenting an Overridden Method

/// <summary>
/// Returns a <see cref="T:System.String"/> that represents the current <see cref="T:System.Object"/>.
/// </summary>
/// <returns>
/// A <see cref="T:System.String"/> that represents the current <see cref="T:System.Object"/>.
/// </returns>
public override string ToString()
{
    return String.Format("{0} {1}", Name, DoseRoute);
}

 

Documenting an Event

/// <summary>
/// Occurs when [allergy detected].
/// </summary>
public event EventHandler AllergyDetected;

 

 

As you can see, the default configuration of GhostDoc is pretty intelligent. Here are some shots of the rules configuration options provided by default:

 

 

(I added the shading in the second shot to mask options that were visible in the previous one.)

 

Users have the ability to change any of these existing rules or add their own. This post is just a brief overview of the product, so I won’t go into details on how to configure a rule at this time. Let me know if you would be interested in more posts that dive into more details on the configuration of GhostDoc.

If you don’t already use it, I encourage you to download it and give it a try. The learning curve is not steep and the benefits are great. Plus, it’s free! One more quick note, VB support is experimental at this time, and it is turned off by default. To enable it, go to the Options tab on the config screen.

GhostDoc download links are here.

My sample project (VS2008) can be downloaded here.