Panopticon Central

a blog on Visual Basic, .NET and other stuff

  Home :: Contact :: Syndication  :: Login
  490 Posts :: 19 Stories :: 3216 Comments :: 622 Trackbacks

News

The information in this weblog is provided "AS IS" with no warranties, and confers no rights.

My Book

Picture

My Recent Posts

Article Categories

Archives

Post Categories

Microsoft Blogs

Samples

Technical Blogs

VB Links

Just a quick one... The PDC build of Whidbey has XML Documentation comments in VB that look something like:

'@ <summary>
'@ A method.
'@ </summary>

The “@” was used as a placeholder while we did some testing and discussion about what the marker for the comments should be. An obvious choice would be ''' (three comment ticks in a row), but we had some concerns that the comment/uncomment block IDE feature might negatively interact with it (i.e. you do “comment block” multiple times on a section of code and all of a sudden you're getting weird XML Documentation warnings).

However, we've decided that we do like ''' the best, so we're going to slightly modify comment/uncomment block to add a space after the comment tick to ensure it won't create XML Documentation by accident. So in the beta, XML Documentation comments will look like:

''' <summary>
''' A method.
''' </summary>

More feedback is always accepted. (Though, please, no accusations that we're changing the syntax because we think VB developers are too dumb to understand “@”... <G>)

posted on Saturday, November 08, 2003 8:33 AM

Feedback

# re: Changes to XML Documentation comments 11/8/2003 10:06 AM Mattias Sjögren
That looks a lot better than '@ - thanks for changing it.

# re: Changes to XML Documentation comments 11/8/2003 11:23 AM julie lerman
''' makes great sense for anyone with a history doing vb. Sorry you took so much flack. I can say that *I* feel a lot better about the whole issue now and I would imagine that many others do as well. Poor Paul!

# re: Changes to XML Documentation comments 11/8/2003 11:44 AM Dewayne Christensen
Thank you, thank you, thank you!

# re: Changes to XML Documentation comments 11/8/2003 1:22 PM Lorenzo Barbieri
I prefer ''' over '@

# re: Changes to XML Documentation comments 11/8/2003 4:11 PM Darren Neimke
Sounds great Paul... will you have the same sections as those provided in C#? I.e.: remarks, summar, example, code, etc.

# re: Changes to XML Documentation comments 11/8/2003 4:49 PM Corrado Cavalli
As we've discussed on alpha ngs I really prefer ''' instead of ugly '@ and i wonder "how C# deals with the same block commenting problem?" Thanks for changing it! :-)

# re: Changes to XML Documentation comments 11/8/2003 6:23 PM Charles M. Carroll
Why does the VB.net team resist the obvious? Comment Begin .... a bunch of well formed XML Comments ..... Comment End This would also allow block commenting mucho code without an IDE, nested comments, and also just makes sense and avoid sightly ' on every line of code that really makes VB.net commenting ugly.

# re: Changes to XML Documentation comments 11/8/2003 7:02 PM Robert Jacobson
Much better. Thanks!

# re: Changes to XML Documentation comments 11/8/2003 7:52 PM Maxim V. Karpov
Paul, I like '@ syntax I think it will not be a problem to VB developers. Personally I do not like multiple single quotes. C# has it different /// make it easy to read, maybe you should use somthing like this '/// :). Anyway, I think it is very good that you are asking people of what they would like. By the way is there word document for VB spec for next release? Thanks, Maxim

# re: Changes to XML Documentation comments 11/9/2003 2:18 PM LeeBarwick
I personally find ''' easier (or less error prone) when typing. I've found using '@ in a hurry produces more errors

# re: Changes to XML Documentation comments 11/9/2003 5:49 PM Paul Vick
To respond to some of the comments so far: * Don't cry for me Julie... The truth is, this is way better than the VB.NET 2002 cycle... * We use the exact same schema as C#, since that's what all the tools understand. * Don't think we haven't considered Comment...End Comment. The problem is that comments seem to visually work better with a non-alphanumeric delimiter. (Why else does nobody use "REM" anymore? It still works, even in VB.NET!) * Maxim, if you're talking about an updated language specification, there isn't one available yet. I don't know when one will be available, but it certainly will be mentioned here when it does! * C# doesn't have a problem with the uncomment block because if you comment //, you get /// which isn't valid XML Documentation.

# re: Changes to XML Documentation comments 11/9/2003 10:44 PM Raj Chaudhuri
Paul Whether alphanumeric or not, block comments are LONG overdue. Please, please make this happen.

# XML Comments in VB.NET 11/9/2003 11:33 PM .NET Weblog
The XML Doc comments for VB.NET make an appearence in Whidbey. Paul has a post on the different ways that they are looking at marking this in the final product. Well I kinda like '@ better that '''. Too much

# re: Changes to XML Documentation comments 11/10/2003 6:14 AM GeorgeNava
How about tick+anglebracket and the smart compiler knows where the well-formed xml ends and considers the whole block as a comment? Just one tick before the bracket, easy...

# re: Changes to XML Documentation comments 11/10/2003 6:46 AM Urs
Please go with ''' and forget the '@. On German keyboards, you have to type Alt Gr+2 every time you want to have an @. Doing this all the time is not very nice.

# re: Changes to XML Documentation comments 11/10/2003 9:15 AM GeorgeNava
Btw, nobody uses REM cuz the tick is better for a one line comment, but for a block it is always better a start/end delimiter like /* comment here */ Comment...End Comment is a great idea for block comments also XmlComment ... End XmlComment would be more specific for xml, no mess, no wild guess And we all know xml comments will have more than one line right? make it clean and easy Implement both and everybody will be happy

# re: Changes to XML Documentation comments 11/10/2003 10:43 AM Jeffrey McManus
Excellent choice. Three ticks will be much easier for everyone to type.

# re: Changes to XML Documentation comments 11/10/2003 11:06 PM Jens Christian Mikkelsen
Little over a year ago, I wrote my own little add-in to VS.NET to extract XML comments from a VB.NET project. My choice then was the three ticks, too. (It is probably a universal constant.) I have used the add-in a lot here for our in-house projects. (BTW - We never had anyone complain about the Comment Block issue.) So I went to the PDC, saw the '@ syntax, came back and modified my add-in and started migrating the documentation for our projects. BUT NOW YOU ARE CHANGING IT BACK! Aaaargh... So I probably should NOT take any actions based on what I learn at a PDC. Anyway, glad you changed to triple ticks. Don't support both. Triple ticks rule.

# re: Changes to XML Documentation comments 11/11/2003 10:56 AM Paul Vick
Yeah, you gotta be careful about relying on too much in pre-beta code! (Actually, there isn't that much that's in the PDC build that's changing, but this is one of them.)

# re: Changes to XML Documentation comments 11/12/2003 9:13 AM Cory Smith
How will this affect people who are using the XML Comments add-in available on GotDotNet? I understand that this was an unsupported release, but just curious if any thought has gone into the interactivity for people who are using this add-in today and moving their code forward with the next release.

# re: Changes to XML Documentation comments 11/13/2003 11:24 AM Paul Vick
Jay, the PM who owns the feature, says that if you're talking about the PowerToy, then it should be 100% compatible because it uses ''' and the standard XML Documentation elements, which is what we'll use. There may be other add-ins that are available on GDN and elsewhere, and it just depends on how they store the comments and what format they use.

# Some REAL Generics in VB.NET Whidbey 11/13/2003 9:23 PM Carl Franklin


# re: Changes to XML Documentation comments 11/17/2003 2:03 AM Alexander Kachalkov
I saw some where this kind of syntax for XML Comments: ['/] It very simple to press two buttons that are near to each other. Just try and you will like it!

# re: Changes to XML Documentation comments 11/17/2003 2:04 AM Alexander Kachalkov
I saw some where this kind of syntax for XML Comments: ['/] It very simple to press two buttons that are near to each other. Just try and you will like it!

# re: Changes to XML Documentation comments 11/17/2003 2:04 AM Alexander Kachalkov
I saw some where this kind of syntax for XML Comments: ['/] It very simple to press two buttons that are near to each other. Just try and you will like it!

# re: Changes to XML Documentation comments 11/17/2003 2:05 AM Alexander Kachalkov
I saw some where this kind of syntax for XML Comments: ['/] It very simple to press two buttons that are near to each other. Just try and you will like it!

# re: Changes to XML Documentation comments 11/17/2003 2:06 AM Alexander Kachalkov
I saw some where this kind of syntax for XML Comments: ['/] It very simple to press two buttons that are near to each other. Just try and you will like it!

# Visual Basic .NET XML Documentation 11/17/2003 11:37 AM Bill Evjen's Blog


# re: Changes to XML Documentation comments 12/28/2003 6:44 AM Paul Laudeman
PLEASE PLEASE PLEASE make the XML commenting work with Intellisense just as it does today in C#. For instance, if I declare a class level variable and reference that variable elsewhere in my class, I should be able to hover over that variable and get the Intellisense to popup with the XML documentation. Likewise, if I reference methods and properties of other projects *in the same solution* I'd like to see it as well -- just as the C# IDE gives you today. This is a huge productivity boost so you don't necessarily have to go to the definition so often. THANKS!

# re: Changes to XML Documentation comments 3/1/2004 11:42 PM Paul Vick
Yup, we plan to fully integrate it with Intellisense!

# re: Changes to XML Documentation comments 3/30/2004 1:18 PM Andrew Novick
I'd like to stay with the '''. I've been using the vbCommentor powertoy from gotdotnet and Ndoc. This combo uses ''' and I and others have lots of comments this way.

# XML Documentation? 4/20/2004 12:23 AM Visual Basic Frequently Asked Questions


# XML Documentation? 4/20/2004 12:50 AM Visual Basic Frequently Asked Questions


# re: Changes to XML Documentation comments 4/20/2004 10:28 AM dru
I to enjoy the ''' syntax. I would like to throw my voice in for support in VB for the same syntax highlighting that C# has on these XML comments.

# re: Changes to XML Documentation comments 6/3/2004 7:09 AM Juan Ma
I'm working in a Standard Documentation for our projects with c# and vb.net

Where I can get some information about this feature in MS web Site? such a guidelines document?

I don't mind about the format, maybe only a ' is greater than use ''' (I think this is a way to make similar VB.NET and C#)

# re: Changes to XML Documentation comments 6/3/2004 11:55 AM Paul Vick
Since VB uses the same XML schema as C#, you can use the same guidelines from MSDN for VS 2003 for VS 2005 as well.

# re: Changes to XML Documentation comments 6/8/2005 6:38 PM Blake
In reference to block comments:
How about using '@ . . . @' for block comments? As for the XML stuff, the three ticks is awesome!

# re: Changes to XML Documentation comments 2/20/2006 6:22 AM Anil Babu. K
i tried this in my system. But i am not getting the comments. can any one help in this.
anilbabu@intermediasoftech.com

# re: Changes to XML Documentation comments 6/9/2006 9:31 AM Roy
Is there a way to customize the xml documentation comments that are inserted by typing ///

EX: Type /// puts in
///<Summary>
/// Author: Roy
/// Date: January 1, 2006
/// <Summary/>

Post Feedback

Title:
Name:
Url:
Comments: