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 –
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 –
Once you select “Document This” option, GhostDoc is going to add the Xml Comments to that particular method/property.
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 –
For a Property –
We can also configure GhostDoc in VS environment.
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.
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 :-).
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.