Changes to XML Documentation comments

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>)

39 thoughts on “Changes to XML Documentation comments

  1. 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!

    Reply
  2. 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! 🙂

    Reply
  3. 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.

    Reply
  4. 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

    Reply
  5. LeeBarwick

    I personally find ”’ easier (or less error prone) when typing. I’ve found using ‘@ in a hurry produces more errors

    Reply
  6. paulvick

    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.

    Reply
  7. Pingback: .NET Weblog

  8. 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…

    Reply
  9. 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.

    Reply
  10. 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

    Reply
  11. 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.

    Reply
  12. paulvick

    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.)

    Reply
  13. 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.

    Reply
  14. paulvick

    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.

    Reply
  15. Pingback: Carl Franklin

  16. 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!

    Reply
  17. 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!

    Reply
  18. 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!

    Reply
  19. 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!

    Reply
  20. 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!

    Reply
  21. Pingback: Bill Evjen's Blog

  22. 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!

    Reply
  23. 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.

    Reply
  24. Pingback: Visual Basic Frequently Asked Qu

  25. Pingback: Visual Basic Frequently Asked Qu

  26. 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.

    Reply
  27. 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#)

    Reply
  28. Blake

    In reference to block comments:

    How about using ‘@ . . . @’ for block comments? As for the XML stuff, the three ticks is awesome!

    Reply
  29. 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/>

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *