Visual Studio Hacks [Electronic resources] نسخه متنی

Hack 70. 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
tooljust 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.

8.4.1. 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.)

8.4.2. 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 8-3.

Figure 8-3. 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 Enteryou 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.

8.4.3. 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.