JumpStart # 11 – Xml Comments for code using GhostDoc Extension

Documentation of code, arrrgh!!! :-) Most of us hate it, but believe me its an important part in SDLC. Especially when it comes to maintenance of legacy code, Documentation is a life savior.

Writing Xml Comments in Visual Studio is not going to be a easy going task (for large projects it’s a nightmare too). So I started using GhostDoc, an extension of Visual Studio, which helps and makes Xml commenting comparatively easier. There are many other extensions available which give the same functionality in writing comments, but in this small JumpStart I would like to show how to get started with GhostDoc.

GhostDoc was created by Roland Weigelt, and now it is under SubMain company License. There are two versions of GhostDoc Products, one is FREE Version and the other is Pro (Paid) Version. For more details on GhostDoc Extension, please visit following resources –

Ghost Doc Download – Click Here

Roland Weigelt, Ghost Doc Author – Click Here

Okay, lets get started with GhostDoc -

First Download the extension (Free version :-)), and install GhostDoc v3.0.10340. Once installed, open Visual Studio (I am using 2010, GhostDoc is compatible with 2008 too). You are prompted to setup HotKey combinations of GhostDoc –

image

For this time, I am not selecting any HotKey, so I am going with “Skip” option. Later it will prompt to create a Configuration settings for GhostDoc, Click “Create” (this can be modified later). Click “Finish” in next window to complete Setup. Now we can get started with writing Xml Comments to our Methods and Properties for our code. Lets see how to use GhostDoc.

I created a sample class in VS 2010. And when I right click any method or property, I will see the following option –

image

Once you select “Document This” option, GhostDoc is going to add the Xml Comments to that particular method/property.

GhistDoc1

Hmmm…Not bad. It wrote the Xml Comment structure for complete method, but remember Ghostdoc is designed to assist us in documenting, but not accomplish the complete document out of its own intelligence, because it cant read a developers mind to actually understand what he intended to do in that particular code. So now our work is to just change the comments appropriately. So what I did was –

GhostDoc2

For a Property – GhostDoc3

 

We can also configure GhostDoc in VS environment.

image

And here you can add rules, Acronyms etc. I never tried them before as I thought I am good with the present support I am getting from GhostDoc, but for larger projects, where you want more customized comment structure, then it is worthy to customize GhostDoc using these options.

image

I want to wrap up about this GhostDoc at this point and leave it for you guys to play around with it. Hope you folks found this extension interesting and useful. Keep using it and forget your burden of Copy-Pasting or typing the comments which is a tradition for most of us :-).

Disclaimer:

All coding and suggestions made in the above discussion is strictly in point of view of the author. It is neither mentioned any where nor even concluded that this is the only possible way to go with, as there will be always a chance for a new approach in achieving the same requirement (in context of programming). The above mentioned code is strictly written and explained for the sake of new comers to C# and ASP.NET world.

You may also like...

  • Jerry Joseph

    It doesn’t seem so convincing that we need this extention. In Visual Studio if we type “///” above a method it will automatically generate an empty comment summary when we can fill. If we use this extension anyway we gotta edit the comment generated by the extention.

  • RamiVemula

    @Jerry –

    Yes you are right, but many people will have different perspectives. I am not saying this is a must to use Extension, but rather I am more interested in investigating the plugin and making it much more better.

    Bottom line I dont expect a plugin or VS to read my mind and generate the comments out of my intenstions. I would rather interested in clicks and getting the coment structure done.

  • Nenad

    How to include tag with Method name ….
    Something like SampleReturnMethod

  • RamiVemula

    @Nenad –

    Try by configuring, I mean add new Rule using the configuration wizard of GhostDoc.

    Thanks.