Code Focused

Take Advantage of XML Comments (Part 2)

On VB columnist Joe Kunk continues his examination of XML comments by extending the XML comment vocabulary with additional default tags in Visual Basic and showing how to process the resulting XML file into API-style reference documentation using the SandCastle Help File Builder.

• By Joe Kunk
• 08/04/2011

In Part 1 of this series, I explored the benefits of XML comments, contrasted their behavior and appearance in both Visual Basic and C#, and detailed the standard Visual Basic XML comment tags. Here we look at extending the XML comment vocabulary with additional default tags in Visual Basic and how to process the resulting XML file into API-style reference documentation using the SandCastle Help File Builder.

VBXMLDoc.xml
Visual Basic and C# share the same XML comment tags. These are: c, code, description, example, exception, include, item, list, listheader, para, param, permission, remarks, returns, see, seealso, summary, term, typeparam, and value. While any valid XML tag is permitted in XML comments, these comprise the collection of tags that natively available.

In Visual Basic, it is possible to extend the XML comment template with additional tags by creating a file named VBXMLDoc.xml and saving it in the appropriate folder. These custom tags appear in IntelliSense when creating XML comments in the same manner as the native tags. Adding custom XML comment tags provides a way encourage standardized documentation items within the code. This capability to extend the standard XML comments template is not yet available for C#.

When present, the VBXMLDoc.xml file overrides the default XML comment behavior, so it must contain the default tags as well as any custom tags. The thirteen code element types defined in VBXMLDoc.xml are Class, Declare, Delegate, Enum, Event, Field, Function, Interface, Module, Operator, Property, Structure, and Sub. The VBXLMDoc.xml with the default tags is shown in Listing 1.

The location for the VBXMLDoc.xml file depends on the operating system and version of Visual Studio as follows:

Windows XP:
Visual Studio 2005 : C:\Documents and Settings\\Application Data\Microsoft\VisualStudio\8.0
Visual Studio 2008 : C:\Documents and Settings\\Application Data\Microsoft\VisualStudio\9.0
Visual Studio 2010 : C:\Documents and Settings\\Application Data\Microsoft\VisualStudio\10.0

Windows Vista or Windows 7:
Visual Studio 2005 : C:\Users\\AppData\Roaming\Microsoft\VisualStudio\8.0
Visual Studio 2008 : C:\Users\\AppData\Roaming\Microsoft\VisualStudio\9.0
Visual Studio 2010 : C:\Users\\AppData\Roaming\Microsoft\VisualStudio\10.0

Adding Custom XML Comment Tags in Visual Basic
Once the VBXMLDoc.xml file is in place, it can be modified to add additional XML comment tags. Note that Visual Studio must be restarted after any changes to the VBXMLDoc.xml file in order for the changes to take effect. The general format of the VBXMLDoc.xml follows the structure shown in below.

<?xml version="1.0" encoding="utf-8" ?>
<XMLDocCommentSchema>
    <CodeElement type="Code Element Type">
        <Template>
            one or more template tags
        </Template>
        <CompletionList>
              one or more CompletionList tags
        </CompletionList>
    </CodeElement> 
    <ChildCompletionList> 
              one or more ChildCompletionList tags
    </ChildCompletionList>
</XMLDocCommentSchema>

Adding a template tag will include the new tag in the default set inserted when the XML comment is created by the triple apostrophe. These tags will appear in the order in which they appear in the VBXMLDoc.xml file. Adding a CompletionList tag provides an optional template tag; the top-level tag is available in IntelliSense but not automatically inserted. Adding a ChildCompletionList tag will make the tag available in IntelliSense as a child to a top-level tag. A custom tag is not restricted to one of these areas; a custom XML tag may appear in any or all of the template, CompletionList, or ChildCompletionList elements, for any or all code elements.

As an example, the class code construct has been modified to include a Developer template tag and a HelpDeskID CompletionList tag as shown below.

<CodeElement type="Class">
    <Template>
        <summary />
        <Developer />
        <remarks />
    </Template>
    <CompletionList>
        <HelpDeskID />
        <include file="" path="" />
        <permission cref="" />
        <remarks />
        <summary />
    </CompletionList>
</CodeElement>

By convention, xml tags are lowercase, but in this case I use PascalCase formatted tag names to identify the custom XML comment tags. Figure 1 shows the resulting behavior in Visual Studio.

[Click on image for larger view.]

Figure 1. Custom XML Comments in Visual Basic

There are some limitations on the custom XML comment tag definitions. It is not possible to provide default values for custom XML tags. If attributes are provided on the custom tags, they are not included when the tag is inserted into the editor, but any attributes added to custom tags in the editor will be written to the assembly’s generated xml documentation file and thus can be passed to the help file build process.

Note that since VBXMLDoc.xml is a standard XML file, itself can be commented with the standard XML comment construct of ‘’. Avoid comments within the Template, CompletionList, and ChildCompletionList tags as they will produce a ‘#comment’ entry in IntelliSense for the XML comments.

Generating Reference Documentation
It may be desirable to produce API-style reference documentation from your source code, to serve as a reference to other developers, or as an aid in future maintenance of the assembly. XML comments are not required to produce reference documentation, but when done well, XML comments produce more informative documentation MSDN-style documentation.

In Visual Basic, the XML comments are extracted and written into the bin folder when a Build is done in Visual Studio. The XML file is named the same as the assembly with an XML extension, and must reside in the same folder as the assembly for IntelliSense to find it. The XML file can also be generated with the command line compiler using the /doc option. See Listing 2 for an example assembly xml file.

There is no help generation integrated into Visual Studio so external tools are required. Microsoft developed SandCastle internally for this purpose and made it available for use as an open-source product. It was announced in July 2006 and released on CodePlex in January 2008. SandCastle reflects across the assembly and integrates the extracted XML comments into the help files.

SandCastle Help File Builder
SandCastle is not a single utility but in fact several standalone utilities that require multiple manual steps in order to produce a usable help output. Fortunately the open-source project SandCastle Help File Builder (SHFB) greatly simplifies the process.

Installing the version of SHFB with Visual Studio 2010 support adds a SandCastle Help File Builder project template to Visual Studio. Generating help is as simple as adding assemblies to the Documentation Sources folder as shown in Figure 2 and then Build the project. This can take several minutes even for smaller files, but fortunately SHFB supports a Completion Notification Plug-In that will send an email on successful completion, failed build, or both.

Possible SHFB outputs are Microsoft HTML Help (CHM), MS Help 2 (HxS), MS Help Viewer (MSHC), and Website (HTML/Asp.Net) as shown in Figure 2. By default, the SHFB places each of the selected outputs in the same folder; use the Output Deployment Plug-In to specify separate output locations for each output type.

[Click on image for larger view.]

Figure 2. SandCastle Help File Builder

SHFB extends the XML comments capability of Visual Studio by enhancing some of the pre-defined tags and adding some of its own as shown in Table 1. Perhaps the most useful is the extension to the code tag that allows the code sample to extract from a region within an external file, allowing the sample to be executable code that can be validated with unit tests. See the Sandcastle Wall Chart (PDF) for full details.

Viewing Custom XML Comments in Help Files
Custom XML comment tags must be enclosed in the <summary> or <remarks> tag in order to be visible in the generated help. The XML tags themselves do not appear, so additional labeling of the content is needed. Explicit formatting is needed to achieve an attractive appearance. This is demonstrated by the XML comments in Figure 3 for VB_Class2 and the resulting CHM help page shown in Figure 4. You see that the custom XML comments with the activity tag were concatenated into a single string in the summary, then formatted to be more readable in the remarks section using para tags.

[Click on image for larger view.]

Figure 3. Custom XML Comments for VB_Class2

[Click on image for larger view.]

Figure 4. Generated Help for VB_Class2 with Custom XML Comments

Commercial Help Generation Tools
SandCastle and SandCastle Help File Builder provide open source tools to generate reference documentation. There are commercial tools that provide additional features and may be a better solution for some developers. These include Doc-To-Help by ComponentOne and HTML Help Builder by West Wind Technologies.

Visual Basic supports the VBXMLDoc.xml file which permits the definition of additional XML comment tags that appear in IntelliSense to help prompt developers to write more standardized and comprehensive documentation in the source code where it is more likely to be kept current with future code changes. C# developers can use the same tags, but without the ability to include custom XML comment tags in IntelliSense.

For both languages these custom XML comment tags are useful to the developer working in the source code, but also can be included in reference documentation generated from the XML comments. This documentation is very important to make working with the code easier for both current and future developers.

Tools like the SandCastle Help File Builder make help generation easier, but significant effort is still required to produce attractive reference documentation. Microsoft should treat reference documentation as an important first-class deliverable from Visual Studio and add templates and features within the core IDE to reduce the effort required and have it more integrated with the coding and build process.

• Get Code Download