Article Options
Premium Sponsor
Premium Sponsor

 »  Home  »  .NET Framework  »  XML Documentation and IntelliSence for Class Libraries in VB.NET
 »  Home  »  Data Programming  »  XML  »  XML Documentation and IntelliSence for Class Libraries in VB.NET
XML Documentation and IntelliSence for Class Libraries in VB.NET
by Paul Nichols | Published  02/21/2003 | .NET Framework XML | Rating:
Paul Nichols

Based in the UK I've been an IT contractor for over 5 years specialising in VB.NET and C# both on both Windows and Web based projects. Please feel free to contact me at mail@pandesolutions.co.uk or see my online CV at www.pandesolutions.co.uk

View all articles by Paul Nichols...

XML Documentation and IntelliSence for Class Libraries in VB.NET

As a VB developer one thing that I've been wondering how to achieve is providing my assemblies with a more professional look by adding summaries, descriptions, help and remarks to the classes, members and parameters. This help is often seen when using commercial assemblies both in the Object Browser and programmatically as you hover over a member shown in your IntelliSence list. Very regularly we must all think, OK what exactly does this parameter mean and even more importantly what does the method actually do!

The way these comments are associated with your class libraries is all through the creation of XML documentation files, which are located and shipped, in the same directory as the assembly.

When I first looked at C#, a nice feature I felt was the XML comments you can use to describe your code. You can then take these comments to build HTML documentation of your code. Strangely this isn't a feature of VB.NET?

At first I hadn't realised that upon compilation you can choose to have Visual Studio take these comments and create the XML documentation file and this is actually what gives you the extra help through IntelliSence. When I did realise this I searched around to find how the same functionality could be achieved for VB programmers.

The first useful link I came across was a Microsoft sample http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnvssamp/html/vbcs_XMLComments.asp. The Microsoft XML tool allows us to point to a compiled assembly and then the left side of the main screen shows, through reflection, the structure of the chosen assembly. The right side of the screen allows several types of comments to be included along with explanations. These are then saved to the XML file with the same name as the assembly (the file name has to be the same). The file can be maintained too at a later date.

The only draw back with this very useful free code is that it works with a complied assembly and doesn't actually attempt to add the comments to source code.What would be nice is to encourage programmers to comment our code, at the same time as those comments leading to XML documentation. This is where the next tool comes in. http://vbxmldoc.tor-erik.net/news.shtmlI believe it's still in Beta 2 at the moment but this program works as an add-in to Visual Studio and allows comments to be added simply as you would in C# but using ''' rather than /// to mark the comment. Then upon compilation, if you choose, the XML document can be produced.

I'm sure there are many more tools out there (for example another XMLDoc program http://www.gotdotnet.com/userarea/keywordsrch.aspx?keyword=VBXMLDoc). But I'm sure that with the use of these two tools documentation and giving your assemblies the professional look should be a breeze.

How would you rate the quality of this article?
1 2 3 4 5
Poor Excellent
Tell us why you rated this way (optional):

Article Rating
The average rating is: No-one else has rated this article yet.

Article rating:3.49999999999999 out of 5
 62 people have rated this page
Article Score25881
Sponsored Links