Deborah's Developer MindScape






         Tips and Techniques for Web and .NET developers.

January 31, 2010

XML Documentation Comments

Filed under: C#,VB.NET,XML @ 2:37 pm

You can document your classes, properties, methods, and so on using XML tags. I’m sure all developers know this at this point, but did you know that you can modify the set of valid tags?

If you are not familiar with XML Documentation Comments (or just XML Comments), you create them differently depending on the language you are using.

In C#:

On the line above the class, property, method, or whatever you are documenting, type three forward slashes.

///
public List<Customer> Retrieve(int Id)

Visual Studio automatically inserts the appropriate XML tags:

/// <summary>
///
/// </summary>
/// <param name="Id"></param>
/// <returns></returns>
public List<Customer> Retrieve(int Id)

In VB:

On the line above the class, property, method, or whatever you are documenting, type three apostrophes.

”’
Public Function Retrive(ByVal id As Integer) As List(Of Customer)

Visual Studio automatically inserts the appropriate XML tags:

”’ <summary>
”’
”’ </summary>
”’ <param name="id"></param>
”’ <returns></returns>
”’ <remarks></remarks>
Public Function Retrive(ByVal id As Integer) As List(Of Customer)

You can then build technical documentation of your API from the XML comments.

In C#:

1. Double-click on Properties for the project in the Solution Explorer.

2. Click on the Build tab.

3. Check the "XML document file" checkbox and ensure  that a file name is specified.

4. Build your project.

All of the XML comments are generated into one XML file.

In VB:

Generating the XML documentation is on by default. To check it:

1. Double-click on My Project for the project in the Solution Explorer.

2. Click on the Compile tab.

3. Check the "Generate XML documentation file" checkbox.

The XML file is generated in the bin\Debug folder for the project.

You can use a product such as SandCastle to generate your technical documentation from these comments.

But what if you want more or different tags than those that are provided? IF YOU ARE USING VB.NET you can do just that.

NOTE: As far as I have seen, this technique is not available in C#.

In VB:

Locate your XML Comment tag file. Mine was here:

C:\Documents and Settings\Deborah\Application Data\Microsoft\VisualStudio\9.0\VBXMLDoc.xml

If you don’t have this file, you can create it following the instructions defined here.

This file contains the definition of the valid XML tags used in XML Comments. You can then add to the contents of this file or edit it as you desire.

For one of my projects, we wanted to add an edit history to each class that included the date, the developer’s name, and a description. So I added the following to the Class code element:

    <CodeElement type="Class">
        <Template>
            <summary/>
            <remarks/>
        <editHistory date="" developer=""/>
        </Template>
        <CompletionList>
            <include file="" path=""/>
            <permission cref=""/>
            <remarks/>
            <summary/>
        <editHistory date="" developer=""/>
        </CompletionList>
    </CodeElement>

We could then create XML comments as follows:

”’ <summary>
”’ Manages a customer class
”’ </summary>
”’ <remarks></remarks>
”’ <editHistory  date="9/14/09" developer="DJK">
”’ Added customer type.
”’ </editHistory>
”’ <editHistory date="10/17/09" developer="DJK">
”’ Added an Email address.
”’ </editHistory>
Public Class Customer

Use this technique any time you want to enhance your XML comment documentation in VB.NET.

Enjoy!

RSS feed for comments on this post. TrackBack URI

Leave a comment

© 2019 Deborah's Developer MindScape   Provided by WPMU DEV -The WordPress Experts   Hosted by Microsoft MVPs