Create XML Comments with VB





Create XML Comments with VB.NET

Visual Studio 2002 and 2003 won't let you use XML comments with VB.NET, but you can use a power toy to make it possible.

XML comments are not just for C# developers any more. XML commenting is a very powerful tool—just because you happen to be developing in VB.NET, you should not be deprived of it.

Normally in Visual Studio .NET 2002 and 2003, VB.NET developers do not have the option of using XML comments. Thankfully, this functionality is added in Visual Studio 2005, but what can you do before then? A power toy called the VBCommenter adds XML commenting to VB.NET for Visual Studio .NET 2003. Using this power toy, you can add XML comments to your VB.NET classes and functions. These XML comments will then be compiled into a single XML file, which can then be processed using any of the available documentation creation tools (the same tools you use with C#).

Before moving on, you will need to download and install the VBCommenter power toy from http://workspaces.gotdotnet.com/VBCommenter.

Using VBCommenter

Once installed, VBCommenter lets you create XML comments by using three apostrophes, much as C# comments use three slashes for XML comments. To create a block of XML comments above a function or class, type three apostrophes and then press Enter. Here is a sample XML section created for a generic sub:

''' ------------------------------------------------------------

''' Project     : TestXMLLib

''' Class     : Class1

''' 

''' ------------------------------------------------------------

''' <summary>

''' This class contains a number of functions that we can call.

''' </summary>

''' <remarks>

''' </remarks>

''' <history>

'''     [James Avery]    10/8/2004    Created

''' </history>

''' ------------------------------------------------------------

You can also create XML comments for classes:

''' ------------------------------------------------------------

''' <summary>

''' This sub goes and does something important. 

''' Throws CannotPerformException if an error is encountered.

''' </summary>

''' <remarks>

''' </remarks>

''' <history>

'''    [James Avery]    10/8/2004    Created

''' </history>

''' ------------------------------------------------------------

Using VBCommenter, you can create comments for any public type including functions, properties, enumerations, and so on. When you compile your application, the VBCommenter power toy will collect all of the XML comments from your file and create a single XML file named <YourProject>.xml. Here is a look at the XML created for the preceding XML comments:

<?xml version="1.0"?>

<doc>

  <assembly>

    <name>TestXMLLib</name>

    <version>1.0.1742.29439</version>

    <fullname>TestXMLLib, Version=1.0.1742.29439, 

    Culture=neutral, PublicKeyToken=null</fullname>

  </assembly>

  <members>

    <member name="T:TestXMLLib.Class1">

      <summary>

 This class contains a number of functions that we can call. 

 </summary>

 <remarks>

 </remarks>

 <history>

     [James Avery]    10/8/2004    Created 

 </history></member>

    <member name="M:TestXMLLib.Class1.DoSomething">

      <summary>

 This sub goes and does something important. 

 Throws CannotPerformException if an error is encountered. 

 </summary>

 <remarks>

 </remarks>

 <history>

     [James Avery]    10/8/2004    Created 

 </history></member>

  </members>

</doc>

From here, you can use this XML file just as it was created from C#. You can use NDoc [Hack #71] to turn this XML into some form of documentation. (You could, of course, use XSLT to transform this XML as well.)

Configuring VBCommenter

VBCommenter allows you to configure a number of settings pertaining to how the power toy operates. These options can be set from the Tools VBCommenter Settings dialog, which is shown in Figure.

VBCommenter Settings dialog


The "Create .xml files when projects are built" setting determines whether the <YourProject>.xml file will be created when the project is built. It is a good idea to uncheck this until you are actually ready to create your documentation. There is no need to create these files every time you build your solution since it slows down the build process. The "Insert XML comments in source" setting enables or disables whether XML comments are inserted when you enter the three apostrophes and press Enter—you will almost always want to leave this checked.

The last setting is the Comment Prefix, which allows you to choose between ''', ', '//, and '@ as the comment prefixes for VBCommenter. You can also specify your own custom prefix in the text box.

Hacking the Hack

One of the benefits of VBCommenter being an open source project is that you can customize the power toy to your own needs. You can download the complete source code from the GotDotNet workspace. With this code, you can modify any part of the power toy that you desire.

One of the areas of the power toy begging to be modified is the XML comments that are automatically inserted when you type three apostrophes and press Enter. All of these comments can be modified in a single file called default-autoinsert.xsl. This file contains an XSL stylesheet that creates the comments based on the type that is being clicked on. Here is the first part of that file:

<?xml version="1.0" ?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 

version="1.0">

<xsl:output method="xml"/>

   

<xsl:template match="/xmldocinfo">

<xsl:if test="code-element-type = 'class'">

---------------------------------------------------

   

Project[TAB] : <xsl:value-of select="project" />

Class[TAB] : <xsl:value-of select="name" />

</xsl:if>

<xsl:if test="code-element-type = 'module'">

---------------------------------------------------

Project[TAB] : <xsl:value-of select="project" />

Module[TAB] : <xsl:value-of select="name" />

</xsl:if>

<xsl:if test="code-element-type = 'interface'">

---------------------------------------------------

Project[TAB] : <xsl:value-of select="project" />

Interface[TAB] : <xsl:value-of select="name" />

</xsl:if>

<xsl:if test="code-element-type = 'struct'">

---------------------------------------------------

Project[TAB] : <xsl:value-of select="project" />

Struct[TAB] : <xsl:value-of select="name" />

</xsl:if>

   

---------------------------------------------------

This first section of the file specifies what the header should include based on what you are commenting. You can see that there are xsl:if elements for class, module, interface, and struct types. If you want to modify the header, you can change it directly in this file. For instance, if you wanted to switch the dashes to asterisks and add a line to specify the use case that this class is part of, here is how you could change the class section of this file:

<xsl:if test="code-element-type = 'class'">

************************************************************

Use Case[TAB] :

Class[TAB] : <xsl:value-of select="name" />

</xsl:if>

I removed the Project part and added a Use Case section. I also switched the dashes to asterisks. (You will also need to change the other side of dashes that follow the group of if elements.)

To get your changes to take effect, you need to build the VBCommenter Solution. (The .xslt file is an embedded resource, so it is embedded in the assembly.) After building the solution, you will need to copy the VBCommenter.dll file from your bin directory to the C:\Program Files\PowerToys for Visual Studio .NET 2003\VBCommenter directory. To do this, you will need to close Visual Studio; otherwise, you will get an error stating that the file is currently in use.

After you replace the file and restart Visual Studio, the new stylesheet will be used. When typing three apostrophes and pressing Enter, you would now see the following comments:

''' ************************************************************

''' Use Case     :

''' Class     : Class1

''' 

''' ************************************************************

''' <summary>

''' 

''' </summary>

''' <remarks>

''' </remarks>

''' <history>

'''     [James Avery]    10/9/2004    Created

''' </history>

''' --------------------------------------------------------------

As you can see, customizing this power toy is easy to do, and there are literally no boundaries to the customization that you can do considering that the full source code is available.


     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows