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 www.msdn.com 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

///<summary>

/// Class level summary documentation goes here.</summary>

///<remarks>

/// Longer comments can be associated with a type or member

/// through the remarks tag</remarks>

publicclassTestClass

{

///<summary>

/// Store for the name property</summary>

privatestring _name = null;

///<summary>

/// The class constructor. </summary>

public TestClass()

{

// TODO: Add Constructor Logic here

}

///<summary>

/// Name property </summary>

///<value>

/// A value tag is used to describe the property value</value>

publicstring Name

{

get

{

if (_name == null)

{

thrownew System.Exception(“Name is null”);

}

return _name;

}

}

///<summary>

/// Description for SomeMethod.</summary>

///<param name=”s”> Parameter description for s goes here</param>

///<seealso cref=”System.String”>

/// You can use the cref attribute on any tag to reference a type or member

/// and the compiler will check that the reference exists. </seealso>

publicvoid SomeMethod(string s)

{

}

///<summary>

/// Some other method. </summary>

///<returns>

/// Return results are described through the returns tag.</returns>

///<seealso cref=”SomeMethod(string)”>

/// Notice the use of the cref attribute to reference a specific method </seealso>

publicint SomeOtherMethod()

{

return0;

}

///<summary>

/// The entry point for the application.

///</summary>

///<param name=”args”> A list of command line arguments</param>

staticint Main(System.String[] args)

{

// TODO: Add code to start application here

return0;

}

}

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.

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!

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

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

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.

Disclaimer

All content provided on this blog is for informational purposes only. The owner of this blog makes no representations as to the accuracy or completeness of any information on this site or found by following any link on this site.

Advise for SpammersThis blog is manually moderated, please stop to post scam, spam and other annoying comments as they will never get approved, thank you.

Support MeDid you enjoy the content of this blog, then just click the banner below, it will give me back some money which I will use to keep running this blog.