Method descriptions

[Dinu Anastasiu]

When one writes a method call in a program, a very useful tip box pops up showing the parameters' name and type for the existing overloads.
In the case of methods belonging to .NET classes, a description of the method and of each parameter is also included.
How can I add such descriptions to my own methods?
Thanks,
Dinu

 

[JohnH]

Write in the three ''' before a method, class or property and the standard comment fields will fill in automatically. When you enter field info that will be used for intellisense editor and object browser.

 

[Dinu Anastasiu]

Method tips

Thanks for your prompt reply.
Sorry, I am not familiar with the three '''. Where are they?

Thanks again,
Dinu

 

[JohnH]

That is very difficult to explain if you don't know what that character is called, but imagine that one character looks like this ' then three of them look like this '''. So you just have to find the ' character on your keyboard and write three of them as explained. Good luck!

 

[JohnH]

OK, they are called "single quotes" or just "quotes". MS call this feature "Xml comments", you can see this described in their feature tour on the IDE page here http://msdn.microsoft.com/vstudio/express/vb/features/ide/default.aspx

"single quotes" and "double quotes" is perhaps the best discription of these characters, since some languages use the double quotes as default quotation marks and commonly refer to those as just quotes..

 

[Dinu Anastasiu]

XML Documentation in Visual Basic

Thank you very much.
Another way to answer the question could be:
1. In the Code Editor, position your cursor on the line above the type or member for which you want to create documentation.
2. Type ''' (three single-quotation marks).
An XML skeleton for the type or member is added in the Code Editor.
3. Add descriptive information between the appropriate tags.
See also: How to: Create XML Documentation in Visual Basic</SPAN>, in Visual Studio 2005 Help.
Thanks again,
Dinu

 

[ImDaFrEaK]

Can you tell me why sometimes I do this and it doesn't work? Sometimes I type ''' and I get the tags to add the correct description. Other times it never works. I even type in or copy and paste the description the way it is supposed to be and it doesn't work. Any ideas?

 

[cjard]

are you attempting to comment a private member? the comments are mainly for other people to use that method - of course, other people outside your class cannot call that method, so i would expect the auto-commenting to only work for members that can be accessed from another class?

 

[ImDaFrEaK]

Yes, I realize that also but good point. No the comments are for public members and I have also made sure the Module or Class is Public as well. It seems to be a glitch for me maybe or I am just doing something totally wrong. I did try to apply the comment to a routine that was private at first then realized it when the comment didn't work. I changed the routine to public like it was meant to be but then the commenting didn't work not only for that routine but anywhere else in my application since then. Weird.

 

[JohnH]

are you attempting to comment a private member? the comments are mainly for other people to use that method - of course, other people outside your class cannot call that method, so i would expect the auto-commenting to only work for members that can be accessed from another class?

The member comments are both for intellisense, for readability and for generating documentation, and all three are perfectly valid reasons for commenting private members. Generating documentation is normally done by two versions, one for public use that hides the not accessible private members and one for internal documentation where the private members are just as important for the work. Commenting privates works fine and you see this if you try, it only takes three keypresses '''. Why would there be a difference? I have to admit not having used this feature extensively, but with the limited usage I have not seen a glitch about it yet.

 

[ImDaFrEaK]

I press ''' over and over and sometimes I get it to work and sometimes I don't. I have a glitch I think, lol

 

[cjard]

Commenting privates works fine and you see this if you try, it only takes three keypresses '''. Why would there be a difference? I have to admit not having used this feature extensively, but with the limited usage I have not seen a glitch about it yet.

Sorry.. i's never tried it, I was just making an assumption - IIRC most the Java IDEs dont put javadoc comment blocks ahead of private method bodies, they just put a normal comment block.. My bad.. :/