Must have VS 2008 Free Plug-ins (2): Ghost-Doc

2 minute read

According to the Wikipedia, a ghostwriter is a

professional writer who is paid to write books, articles, stories, reports, or other texts that are officially credited to another person.

As the name seems to imply, Ghost-Doc plug-in for Visual Studio is something like that: instead of typing in the XML documentation for your source code yourself, Ghost-Doc does the heavy-lifting and fills it for you.

Suppose you have a very simple class like the following:

public sealed class TestGhostDoc
{
double CalculateVAT(double priceOfGoods, double VATPercentage)
{
return (priceOfGoods + priceOfGoods * VATPercentage);
}
}

Now you want to add XML documentation for the CalculateVAT member function. All you have to do is to right-click somewhere on line 3 (I prefer to use the CTRL + SHIFT + D since I love shortcuts), select “Document This”, and Ghost-Doc will fill the XML documentation for you like the following:

public sealed class TestGhostDoc
{
/// <summary>
/// Calculates the VAT.
/// </summary>
/// <param name="priceOfGoods">The price of goods</param>
/// <param name="VATPercentage">The VAT percentage</param>
/// <returns></returns>
double CalculateVAT(double priceOfGoods, double VATPercentage)
{
return priceOfGoods += priceOfGoods * VATPercentage;
}
}

As you can see, Ghost-Doc, beside filling the structure for you, also fills the contents using a set of rules based on the order of the words (the only thing that is left is filling the content of the returns tag). Note that words are recognized successfully only if you use the recommended Camel and Pascal casing appropriately (which you ought to be doing anyway because you follow to the naming conventions).

Member functions is not the only place where you can use Ghost-Doc: class names, constructors, enums, properties, event, etc… they are all supported as expected.

namespace TestGhostDoc
{
/// <summary>
///
/// </summary>
public sealed class User
{
/// <summary>
/// Gets or sets the first name.
/// </summary>
/// <value>The first name.</value>
public string FirstName { get; set; }

/// <summary>
/// Gets the address.
/// </summary>
/// <value>The address.</value>
public string Address { get; }
}
}

Can you spot the difference between the documentations of the two properties that Ghost-Doc has generated?

Advanced use

Ghost-Doc has a complete customization window where you can:

  • modify/add templates that Ghost-Doc uses to document a language element
  • define your own acronyms, that will always be rendered in all-caps by Ghost-Doc, even if you have written them in lower case inside a language element name to be compliant to the naming conventions
  • modify/add the list of words which define qualities, that Ghost-Doc will reorder in a special way. For example, since size is on this special list "FileBufferSize will be worded as “the size of the file buffer” instead of “the file buffer size” .
  • modify/add the list of words that shall never be preceded by “the” (the so called “no the” words).
  • Modify the way true, false, and null keywords are represented
  • Create a custom text that will be appended to all comments the first time they are created; this text can optionally be dynamic and include the name of the author, or the current date, etc.. (this would be a bit over the top IMHO since it would be repeated for each and every function, property, etc…).

Updated:

Leave a Comment