Xml code commenting and automated code documentation was introduced in Visual Studio .NET Beta 1 for C# developers, a brilliant feature that with a little change in the "code commenting routine" made it possible for a developer to automatically generate documentation from comments embedded within the code. Moreover, it defined a consistent way of commenting code for all C# developers. For some reason the VB.NET development team at Microsoft still hasn't added this feature into the third release of the IDE, Visual Studio .NET 2003. But not to worry, Microsoft developers have developed a VB.NET code comment add-on to the IDE made available through www.gotDotNet.com.
In this article we will take a closer look at code commenting, the gotDotNet "VBCommenter", modifying the VBCommenter so that the code comment layout and data generated are configurable, and using an open source documentation generator, "NDoc."
When developing C# within the Visual Studio .NET Integrated Development Environment (IDE), Xml formatted comment sections are dynamically generated by entering a sequence of 3 slash characters ("/") above any code constructs. Visual Studio internally examines the construct and its signature and generates a simple XML Meta tag markup.
Example:
Function MemoryStream FileLoad(String sPath){ }
By entering 3 slashes on the line prior to this method signature the following Xml markup is inserted automatically
///<summary>
///
///</summary>
///<param></param>
///<returns></returns>
Function MemoryStream FileLoad(String sPath) { }
The developer can then add a description in the summary section and provide further details including addition Xml markup.
Note: A suggested collection of tags and their recommended usage can be found within the MSDN help files at:
Ms-help://MS.VSCC.2003/MS.MSDNQTR.2003FEB.1033/csref/html/vclrftagsfordocumentationcomments.htm
Or online at: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vclrfTagsForDocumentationComments.asp
It is also possible to have Visual Studio generate a single Xml document containing a compilation of all the XML meta data on build. An Xsl Transform can be applied to the Xml document to create a rather large Html document. Another option is to generate a comment Web site based on the project dll and XML code comments. The developer simply has to select "Tools" --> "Build Comment Web Pages" from within the IDE.
It's important to note that "Comment Web Pages" are also available to VB .NET projects, however, any Xml comments added to code are ignored and not rendered within the comment Web pages.
For the C# developer in Visual Studio, automated code documentation is relatively easy and a standard practice. But, out of the box Visual Studio does not provide this to VB .NET developers. For many, this is one important consideration when deciding which language to migrate to. However, this should not be a deciding factor The IDE development team at Microsoft built the development environment in a way so third party plug-ins could easily be created and integrated with the tool. Many third party add-ons were ready before Visual Studio .NET was first released.
In fact Microsoft supports a Web site dedicated to .NET developer community driven projects, www.gotDotNet.com. The site consists of workgroups that focus on specific add-ons. Anyone can join these workgroups and contribute to the ongoing development of the add-ons.
Since its first release there have been several third party Visual Studio add-ons and utilities built to add Xml documentation functionality for VB.NET developers; many can be found on the Web for a small fee. A solid entry into the foray is the "VBCommenter" from www.gotDotNet.com. This Visual Studio add-on is available as a free download. The workspace for the VBCommenter is active so the code base is constantly being updated. If you find a bug, you can check the bug tracking at the site to either report it or determine if there is a new version that includes the fix.
So what exactly does the VBCommenter do?
The VBCommenter provides automated Xml documentation within the IDE while writing VB .NET code. Once the add-on is installed, the developer simply types three VB.NET comment characters (''') prior to the start of any code construct and Xml formatted comment sections are dynamically generated.
For example:
Public function FileLoad(ByVal sPath as String) as Memorystream
' Code goes here ...
End function
After typing in three consecutive apostrophes prior to the function ( ''') the following markup will be inserted automatically:
'''----------------------------------------------------------
'''Project: [project name]
'''Function: [Class name].FileLoad
'''<summary>
'''
'''</summary>
'''<param name="sPath"></param>
'''<returns></returns>
'''<history>
''' [logged in user name] [date] Created
'''</history>
'''-----------------------------------------------------------
Public function FileLoad(ByVal sPath as String) as Memorystream
' Code goes here ...
End function
Note: The tool provides some customization. You can change the character sequence to a single apostrophe ('), an apostrophe followed by the "@" symbol ('@) or the default 3 apostrophes (''').
As you can see there is a little more here than just empty XML. The Project Name is retrieved from the environment as well as class and function name. Note the history node. This node is configured in a way that it can be toggled on or off by selecting a check box within the IDE. Other data gathered, but not displayed, includes the param data type (a Boolean indicating if the param is a "Value" or "Reference" type parameter), and the data type the method returns. Also, note the dashed lines and the commented text that is not within XML tags:
'''----------------------------------------------------------
'''Project: [project name]
'''Function: [Class name].FileLoad
When the Xml document is generated, only the Xml tagged sections of the comment block are extracted. The rest is ignored. So it is possible to auto generate comments that are intended for the developer working with the code, and not the generated documentation.
It should be apparent that this add-on gives the VB.NET developer more automated commenting power than what is built into C#. So what's the catch? There are a few:
- Since it is developed by a community, it is not supported by Microsoft. If you run into problems with it, your only recourse is to get help through the user group for the VBCommenter workspace on www.gotDotNet.com
- It's a work in progress, so it may have some shortcomings that are not readily apparent.
- It is built for Visual Studio .NET 2002 or 2003 only. There are different project files for each version. In this article we will only be working with the version for VS .NET 2003.
- There is no built in functionality for generating code documentation from the XML, and the "Build code comment pages" utility built into the IDE for C# won't evaluate the XML document generated by the VBCommenter.
So, I have cool XML markup in my comments. What do I do with it?
There are several Xslt style sheets available on the Web, and several utilities that can consume the Xml document and generate some code documentation. One of the better tools I've encountered is a tool called NDoc.
Like the Power toys NDoc is built by a community of developers working out of a workspace at SourceForge (http://ndoc.sourceforge.net/). NDoc can be used to generate code documentation for several different environments and platforms. For .NET developers, MSDN-style compiled help files and a Web site that is similar to that generated by Visual Studio.NET's "Build Comment web pages"are just a few clicks away.
Note: NDoc can also generate an MSDN-style compiled help file from the Xml generated by C#. C# document generation was built into NDoc way before VB commenting add-ons were available. NDoc itself is written in C#.
• If the VBCommenter is so good, why do we need to modify it? >>
