A common stereotype of programmers has them focusing on the code while ignoring the documentation. Coding is so much more fun, after all, and the documentation often seems, well, superfluous.

This is one of those stereotypes that arose because it is often true. Would making the documentation process easier make a difference? Helixoft, the makers of VSDocman 3.0, think so, and that's precisely what this product aims to do.

It's important to understand that VSDocman does not produce end-user documentation — which would actually be quite a trick, when you come to think of it! Rather, it produces documentation for developers, documentation that includes information about a project's classes, forms, methods, properties, etc. It will be particularly useful in situations such as when you have written an API to market to other developers and want to create the documentation, or when a team of developers is working on a project and you want to let each developer know what the others are doing.

VSDocman works with Visual Basic and C# projects in Visual Studio, where it installs as an add-in. It can work with Visual Basic, C#, and ASP.Net projects. There are several output formats available, including HTML Help, Help 2, RTF, and XML. XML output is an option, permitting you to generate the documentation in a form that can be processed by other tools. Finally, you can define your own custom text-based output format.

You can generate Intellisense and F1 help, and the output can include Object Browser information. The output is modeled on MSDN documentation and includes a table of contents, index, search pane, language filter, and so on.

Figure 1. VSDocman output is modeled on MSDN help and provides the same tools.

A sample VSDocman topic is shown in Figure 1. You can see that it looks identical to the Visual Studio MSDN documentation.

VSDocman is option-rich and lets you configure your documentation just about any way you want. You can, for example, decide whether to include or omit information about classes, methods, properties, events, variables, structures, and all other components of a Visual Basic or C# program.

Figure 2. The VSDocman options dialog box gives you full control over your documentation project.

You can determine if only Public members are documented or Private, Protected, and Friend members should be included as well. You can control which elements are automatically included in source code comments. The default settings are okay for many people, but it's nice to know you have all this control if needed.

VSDocman adds two commands to the context menu that is displayed when you right-click in source code. The Add XML Comment command adds the shell of an XML format comment (JavaDoc comments are supported too) just before the start of the method that you clicked. The comment looks like this (shown with the opening line of the method):

''' <summary></summary>
''' <param name="worker"></param>
''' <param name="e"></param>
''' <returns></returns>
Function ComputeWithThread(ByVal worker As BackgroundWorker, _
    ByVal e As DoWorkEventArgs) As String

You can see that the comment shell includes an elements for a summary, one element for each of the method's arguments, and an element for the return value (If you click outside a method, VSDocman adds a simpler comment, containing only a Summary element, at the start of the class).

Figure 3. The VSDocman comment editor in WYSIWYG mode.

You can add information to these elements directly in the VS editor or you can use the second VSDocman context menu command, Comment Editor, to open the comment editor. This editor, shown in Figure 3, gives you a WYSIWYG view of how the method's help entry will look, and lets you enter the required information. The editor also has a non-WYSIWYG mode.

When you are finished, the information is transferred to the source code comment as shown here and is included in the documentation that VSDocman generates.

''' <summary>This method performs the Julia calculations using a new
''' BackgroundWorker thread.</summary>
''' <param name="worker">The BackgroundWorker object.</param>
''' <param name="e">The arguments to the BackgroundWorker object.</param>
''' <returns>A boolean indicating success (True) or failure.</returns>

The output created by VSDocman is localizable with several built-in languages (English, French, German, and Spanish). The documentation can be deployed to target computers royalty-free, and there it integrates with the existing Visual Studio help.

All in all, I found VSDocman to be a well-designed and very useful tool. It may be overkill for relatively simple one-programmer projects, but as things get more complicated and more developers get involved, the need for good source code documentation can be critical. VSDocman lets you create this documentation in a way that is easy, consistent, and creates documentation in a form that developers already know how to use.