XML comments in VB2005

JumpyNET

JumpyNET

Centurion
Joined
Apr 4, 2005
Messages
196
I've been trying the XML commenting in VB2005. But with no success. :(

When I type the three apostrophes and try to add some comments I get an error message saying that I need a language element first. Could someone post an example of XML commenting in VB2005, please?

I've tried this for example:
Code: 
'''<color=red><b>My comment</b></color>
 
The XML comments are associated with a language element such as a data member, method, namespace, class, etc. Also, while you can put anything you want into XML comments and they will all be ripped out, there are specific XML comments that are relevant to intellisense and documentation tools like NDoc.

Try defining a method, then going back and typing '''. You should get an intellisense pop-up that will guide you with regards to VS aware XML comments. As I said, though, you can put anything you want in the comments.
 
Sorry, you mentioned you wanted an example:

Visual Basic: 
''<summary>Comment my class so that folks know a little bit about it.</summary>
Public MustInherit Class ImplementorBase

    ''' <summary>
    ''' Since this is protected it will be seen by inheritors
    ''' </summary>
    ''' <remarks>And if there is any more information about this member I want my users to know, I'll put it here.</remarks>
    Protected _files() As String = Nothing
    ''' <summary>
    ''' The means by which information is given back to the user.
    ''' </summary>
    ''' <remarks></remarks>
    Protected _reporter As FeedBack.sendFeedBack
    ''' <summary>
    ''' Indication of the content of the data the class will handle and report on.
    ''' </summary>
    ''' <remarks>Appropriate markings must be made on all generated reports.  This responsibility is left to the user.</remarks>
    Protected _classification As FileClassification

   
    ''' <summary>
    ''' Creates a new ImplementorBase
    ''' </summary>
    ''' <remarks>The file classification will be set to unclassified for assemblies built under debug, secret for release. 
    ''' In almost all cases the default for deployed assemblies will be secret.</remarks>
    Public Sub New()
#If DEBUG Then
        Me._classification = FileClassification.Unclassified
#Else
        me._classification = FileClassification.Secret
#End If
    End Sub

    '''<summary>Returns an array of strings containing all the data files for this class</summary>
    '''<author date="2005-10-28">OJ Simpson</author>
    Public ReadOnly Property DataFiles() As String()
        Get
            Return _files
        End Get
    End Property

    ''' <summary>
    ''' Gets and sets The classification of the data processed by this class
    ''' </summary>
    ''' <remarks>Appropriate markings must be made on a file determined by the classification inputted here.</remarks>
    Public Property Classification() As FileClassification
        Get
            Return Me._classification
        End Get
        Set(ByVal value As FileClassification)
            Me._classification = value
        End Set
    End Property

    '''<summary>Reports a message and a status back to the GUI</summary>
    '''<param name="message">The message to send back to the GUI</param>
    '''<param name="returnCode">The type of message that is being returned</param>
    '''<author date="2005-10-28">OJ Simpson</author>
    Public Overridable Sub Report(ByVal message As String, ByVal returnCode As FeedBack.ReturnCode)
        _reporter(message, returnCode)
    End Sub
End Class

The generated XML will look something like this for the constructor and DataFiles property. There's more to this doc, but it's auto-generated so this is more for learning's sake:
Code: 
<member name="M:BKTech.ImplementorBase.#ctor">
	<summary>
 Creates a new ImplementorBase
 </summary>
	<remarks>The file classification will be set to uncalssified for assemblies built under debug, secret for release. 
 In almost all cases the default for deployed assemblies will be secret.</remarks>
</member>
<member name="P:BKTech.ImplementorBase.DataFiles">
	<summary>Returns an array of strings containing all the data files for this class</summary>
	<author date="2005-10-28">OJ Simpson</author>
</member>

As you can see, I included an author tag that tells me who "owns" the chunk of code. That isn't really necessary and is not supported by the VB 8 compiler. It's just a convention developers at my company adopted so we know at a glance about how old something is and who to talk to when something breaks (though technically we could get all this information from CVS).

I found extensive documentation on the XML file and XML summaries at one point, I'll see if I can find it again.
 
Be careful about using XML comments in VB.NET 2005, there seems to be some kind of memory leak. I have a large project with XML comments and I have to shut down VB.NET every 20 - 30 minutes when I am editing a file that includes XML comments. If I don't, Visual Studio will slow tremendously and then crash.

If I am editing a file in the same project that does not have XML comments, I can work all day with no problems. They have supposedly found and fixed this bug, but refuse to release it to developers until they release the first service pack.

Todd
 
I have also heard about that problem but I haven't experienced it yet. I guess my projects aren't big enough. By the way, I think you can get a beta preview of VS2005 SP1 if you were interested. Go here and click on available programs.
 
Gues XML isn't what I was looking for.

I gues I had understood wrong the whole idea of XML encoding. I thought I could format the comments shown in the VB code editor with it (color, bold, italic).

When and why do people really use XML commenting?
And is there another solution to my problem?
 
Consistent comments and auto documentation

JumpyNET said:
When and why do people really use XML commenting?
Click to expand...
For one thing, it provides a consistent template for comments. However, the main reason is that it allows you to create an HTML help file for your code (using NDoc). It is an extremely good reference for anyone that may need to maintain your code, including yourself.

And is there another solution to my problem?
Click to expand...
I'm not really sure why you would want to format your comments. I think that is more complicated than you need to get with code comments.

Todd
 
You can put any valid XML tags in the XML comments. If you really want bold, then go to town. NDoc is extremely useful and well worth checking out. XML comments are also used to populate the intellisense descriptions.
 
I would say that the biggest use for XML documentation is the Intellisense. Intellisense is very important in modern programming. There is so much functionality at your fingertips that you can never be expected to learn everything. Intellisense provides a high level of documentation that’s available as you code, saving you the trouble of looking up functions, what they do, what parameters they accept, etc. in reference material. XML documentation is the final touch: the actual descriptions of the code elements, allowing you to key through classes or functions and find what meets your needs or explaining what a specific parameter does. That is one of the things that make programming with the .NET Framework so easy. Using XML code comments is a very easy way to provide this documentation. Additionally, it provides a standard practice for commenting your code as well, explaining what the elements are not only to the programmer who uses your compiled DLL, but your colleague who writes the class with you.

I have recently begun using the code comments on everything I code to make sure that everything is well documented, so that a year down the road, I don't look at my own code and end up scratching my head.
 
Back
Top