Impersonation ClassUsing the Using Statement

Introduction To XML Comments

May 19th, 2007

XML Comments tell the story of your program 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:

Intellisense Popup Example

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.

Share This Article: These icons link to social bookmarking sites where readers can share and discover new web pages.
  • Digg
  • del.icio.us
  • Reddit
  • StumbleUpon
  • Technorati
  • DotNetKicks
  • DZone

Entry Filed under: VB.NET Tutorials


Rate This Article:

Not That GoodCould Be BetterOKGoodGreat (No Ratings Yet)
Loading ... Loading ...

Leave a Comment

Required

Required, hidden

Some HTML allowed:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Trackback this post  |  Subscribe to the comments via RSS Feed


Visit Me At My New Site, Programming In C#

Most Popular Articles

Highest Rated Articles

Categories

Most Recent Articles

Feeds

 Subscribe in a reader

To subscribe by e-mail
Enter your address here

Delivered by FeedBurner

VB Opportunities

Archives