Introduction To XML Comments

May 19th, 2007

Maybe you’ve wanted to use a standard comment method but you couldn’t come up with a good method that everyone in your organization could agree on. Maybe you’ve wondered how to have your components display information in the object browser or in Visual Studio’s Intellisense engine. XML Comments are the way to do this and more.

Adding XML comments to your VB.NET application created in VS 2005 is easy, just type in three apostrophes - ”’ - just before a sub or function and the following template will appear:

    ''' <summary>
    '''
    ''' </summary>
    ''' <param name="param1"></param>
    ''' <param name="param2"></param>
    ''' <param name="param3"></param>
    ''' <returns></returns>
    ''' <remarks></remarks>

The <returns> section isn’t included with Sub comments.

Or you can type the ”’ before a property and get this result:

    ''' <summary>
    '''
    ''' </summary>
    ''' <value></value>
    ''' <returns></returns>
    ''' <remarks></remarks>

Or before a variable and get this result:

    ''' <summary>
    '''
    ''' </summary>
    ''' <remarks></remarks>

What if the XML comment template doesn’t appear? Don’t despair, go to the My Project|Compile section and check the box to “Generate XML Documentation File” and they’ll start working for you.

Using XML comments not only provides a standard way to communicate the purpose of a section of code or variable within the code itself but exposes it externally as well. The Summary section of the comment is what gets displayed in Intellisense popup, as shown here:

This helps you and others have a quick reference to what the particular item is supposed to do. This can be particularly useful for overloaded functions or other complex situations.

Beyond the simple Intellisense functionality, XML comments create an XML documentation file when you compile your project. This file can be used by documentation programs like NDoc and Microsoft’s new SandCastle tool to build professional looking documentation. Creating such documentation becomes easy with XML comments and not such a tedious chore like it often was in the past.

Entry Filed under: VB.NET Tutorials

Rate This Article:

(No Ratings Yet)

 Loading ...