Automating Documentation with VBCommenter
- Yes, It Really Works!
- Changing VBCommenter Behavior
- Seeing Is Believing
- What's Missing?
- The Bottom Line
When I first saw VBCommenter mentioned online, I thought it would be another in a long series of disappointing documentation tools for Visual Basic .NET developers who longed for the same useful tool that C# developers have. When writing a C# application, all you need to do is type three slashes (///) to start a comment that you can output to an XML file and eventually transform into documentation for your new component or application. For some strange reason, Microsoft felt that Visual Basic .NET developers wouldn't want or need this handy feature, and tool developers have been trying to catch up since.
Yes, It Really Works!
You can download VBCommenter from the GotDotNet site. The download and installation requires only a few minutes, even if you rely on a dial-up connection. After installation, I clicked Start, PowerToys for Visual Studio .NET 2003, VBCommenter and saw only a help file, so I was expecting a fairly worthless utility that only had one or two interesting features (if it had any at all). But it turns out that the interface is seamless. I started by creating a new class project. Typing three single quotes (''') and pressing Enter created a comment for the class that looked like this:
''' ----------------------------------------------------------------------------- ''' Project : MyClass ''' Class : MyMath ''' ''' ----------------------------------------------------------------------------- ''' <summary> ''' ''' ''' </summary> ''' <remarks> ''' </remarks> ''' <history> ''' [John] 5/21/2004 Created ''' </history> ''' -----------------------------------------------------------------------------
VBCommenter added all this information based on the project settings. I typed a summary and then pressed Enter after the <remarks> tag. Interestingly, VBCommenter automatically added three single quotes for me so I could simply start typing the remarks I wanted to add for the application. Little touches like this kept popping up the entire time I used VBCommenter.
The comments VBCommenter creates are unique for each method and property. When you create a standard constructor, VBCommenter adds entries for a summary and remarks. Methods that include a return value or input arguments automatically receive entries for the return value and associated arguments. Properties even include special entries for the value the property allows as input or provides as output. As a plus, the entries look very much like the entries used by C#, so anyone who uses both languages will feel comfortable.
After you add your comments, build the project. The XML file containing the class or application documentation appears in the \bin folder so you don't have to do anything special to create it. (Contrast this with C#, in which you have to make a change to the build setup to ensure that you get the XML output—although the change isn't difficult, it also isn't automatic.) The file has the same name as the project with an XML extension, so it's ready to use immediately.
I checked out the XML file, and it's very similar to the one that C# creates. In fact, the two languages produce files that are so close most utilities designed to work with the C# output won't notice the difference when you use them with VBCommenter output. In fact, I haven't seen any utilities that won't work, with one exception discussed in the "What's Missing?" section of this article.