Introduction

Almost 10 years ago now I used to be a Java developer in Motorola. After a long hiatus in the embedded systems and a job change, I have come back to enterprise development, this time in .Net.

I remembered that in the good ol’ days it required 2 steps to see the final rendering of the XML documentation: firing javadoc (usually from within an ANT task) and the open up the content in a browser.

I was quite surprised to see that in the .Net area seeing the final output of the docs was not as straightforward as I hoped for. Yes, there was NDoc to parse the XML, but its development stopped around 2005 and it’s doesn’t support anything beyond C# 2.0. There’s also Sandcastle, but to make it work for me it has required a few downloads and a bit of tweaking here and there. And integrating it into my NAnt task had not been that easy either. But somehow in the end I have pulled that out.

Therefore I have been pleasantly surprised when I met CR Documentor, a little plug-in for visual studio that let’s you see your XML documentation as you write it. It’s almost like having a WYSIWYG editor, without having to launch Sandcastle, wait for the complete build, and open up the browser.

Installation

• Requirements:
  • Visual Studio 2005 or greater (I am pretty confident that you need at least a Professional version as opposed to Express). I am running it on Visual Studio Team System 2008, not sure whether it works also on 2010.
  • The DXCore plugin framework from DevExpress. Possibly the best (and only?) way to get it is to get through the excellent free CodeRush Xpress for C# and VB
• Download the plugin: CR Documentor is hosted at Google Code at this link.
• Copy the dll in your DX-Core plugin-folder (C:\Users\<username>\Documents\DevExpress\IDE Tools\Community\PlugIns)
• Restart Visual Studio

Usage

1. CR Documentor adds itself in the right click menu, close to the bottom. From the submenu, choose “Show CR_Documentor window”.
2. A new window opens up in floating mode (I prefer to dock-it to the right side together with my solution explorer and luckily the plug-in remembers this choice every time I open the window after closing it and at startup).
3. Now every time your cursor is on an XML doc, you can see the preview in the Documentor window. See for example when I put the cursor on the XML doc of a class: I get a complete picture of the documentation for that class and its methods all in real time.
   
4. There are a few other features that I don’t use very often. All of them are accessible by the right-click content sensitive menu:
   • Expand/Collapse all XML comments in the editor
   • Insert XML docs templates (I prefer to use GhostDoc for that).

Configuration

Like all DXCore plugins, you can access to the configuration by pressing ALT+CTRL+SHIFT+O combination. I like to check all my options to Sandcastle because that’s the tool that I will be using to create the final XML documentation.

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:

In these tabs 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…).

With Ghost-Doc, you have no more excuses not to write complete and accurate XML source code documentation!