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. ”’ 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!

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

  3. Why does the 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 commenting ugly.

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

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

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

  7. Pingback: .NET Weblog
  8. 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…

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

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


    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

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

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

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

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

  15. Pingback: Carl Franklin
  16. 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!

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

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

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

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

  21. Pingback: Bill Evjen's Blog
  22. 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.


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

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

  25. I’m working in a Standard Documentation for our projects with c# and

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

  26. In reference to block comments:

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

  27. Is there a way to customize the xml documentation comments that are inserted by typing ///

    EX: Type /// puts in


    /// Author: Roy

    /// Date: January 1, 2006

    /// <Summary/>

Leave a Reply