Month: January 2011

VSDocMan review–Auto generate VS Help

In these days I have been busy in the office by implementing a mechanism of C.I. (Continuous Integration) by releasing some facilities assemblies so that the developers that are working with me will be able to work always with the latest version of a specific .dll.

One of the most important thing I noticed when you work with a third-party or a legacy .dll is the documentation needed within the code. If you think for a moment on what you do when you work with .NET Framework, every time you do not know how to use a specific component or a specific class, you simply type and you start to search in the help directory for some sample code or for a documentation.

The same important thing has to be done when you work with a third-party component or simply when you are in charge of releasing a facility assembly/framework like I do in my office.

Before showing you what I have found over the internet to solve the problem of generating the documentation, I want to explain you a little bit how the Visual Studio documentation system works.

Visual Studio documentation mechanism

One of the features included in Visual Studio, since one of the first version (maybe 2003/2005?) is the XML embedded documentation that allows you to write documentation in an XML format like the following example:

Sample documented Class
  1. /// <summary>
  2. /// Class level summary documentation goes here.</summary>
  3. /// <remarks>
  4. /// Longer comments can be associated with a type or member
  5. /// through the remarks tag</remarks>
  6. public class TestClass
  7. {
  8.     /// <summary>
  9.     /// Store for the name property</summary>
  10.     private string _name = null;
  12.     /// <summary>
  13.     /// The class constructor. </summary>
  14.     public TestClass()
  15.     {
  16.         // TODO: Add Constructor Logic here
  17.     }
  19.     /// <summary>
  20.     /// Name property </summary>
  21.     /// <value>
  22.     /// A value tag is used to describe the property value</value>
  23.     public string Name
  24.     {
  25.         get
  26.         {
  27.             if (_name == null)
  28.             {
  29.                 throw new System.Exception(“Name is null”);
  30.             }
  31.             return _name;
  32.         }
  33.     }
  35.     /// <summary>
  36.     /// Description for SomeMethod.</summary>
  37.     /// <param name=”s”> Parameter description for s goes here</param>
  38.     /// <seealso cref=”System.String”>
  39.     /// You can use the cref attribute on any tag to reference a type or member
  40.     /// and the compiler will check that the reference exists. </seealso>
  41.     public void SomeMethod(string s)
  42.     {
  43.     }
  45.     /// <summary>
  46.     /// Some other method. </summary>
  47.     /// <returns>
  48.     /// Return results are described through the returns tag.</returns>
  49.     /// <seealso cref=”SomeMethod(string)”>
  50.     /// Notice the use of the cref attribute to reference a specific method </seealso>
  51.     public int SomeOtherMethod()
  52.     {
  53.         return 0;
  54.     }
  56.     /// <summary>
  57.     /// The entry point for the application.
  58.     /// </summary>
  59.     /// <param name=”args”> A list of command line arguments</param>
  60.     static int Main(System.String[] args)
  61.     {
  62.         // TODO: Add code to start application here
  63.         return 0;
  64.     }
  65. }

By using this documentation technique you are giving to your code an additional immeasurable value; especially if you work with some Visual Studio plugin like Resharper, for example, you will come up with a nice and well formatted intellisense suggestion if you decorate the code in this way.


If you want to learn more about it, MSDN offers a great section about the XML documentation in Visual Studio 2010 and how it should be used.

This is a great article that gives you a full overview of this technology:

Documentation with VSDocMan

Last week, after I started working on this C.I. project I just realized that now, more than everything, the other guys that will use my code will need tons of documentation in order to understand how to use my toolkits an facilities. Well I do not want to “blown my own trumpet” but I can easily say that I usually document whatever I write and that I use a lot Resharper and StyleCop to make my code readable and uniform. Unfortunately I am very allergic to .chm files in general.

I have this tool that is called VsDocMan my lifeline and I want to show you how it works; trust me it is simply AWESOME! Hot smile

First of all you can generate VS documentation with a simple Click on the toolbar or in the context menu; in fact VSDocMan allows you to self-document your classes with some pre-defined XML schemas

Automatic insertion of XML comments

Another interesting feature is the Comment Editor command, with this command VSDocMan will show you an interactive MSDN style documentation of how the final doc will look like so that you can easily change your documentation structure in a WYSIWYG editor without the need of struggling with the ugly XML

Editor for XML documentation comments

Plus it allows you to generate a dynamic class diagram that is clickable and that points to the corresponding documentation file!

VSDOCMan generates a lot of different documentations: .chm, MSDN style, MSDN V2, HTML, a full MSDN HTML web site and much more. It is very cheap in my opinion for what it does and if you are looking for a professional and fully working solution to generate documentation from your code, you should seriously consider to spend some time and money on this AWESOME product.

As usual, my two cents. Just kidding