30

According to this article, it's possible to get multiline XML comments -- instead of using ///, use /** */. This is my interpretation of what multiline comments are, and what I want to have happen:

/**
 * <summary>
 * this comment is on line 1 in the tooltip
 * this comment is on line 2 in the tooltip
 * </summary>
 */

However, when I use this form, the tooltip that pops up when I hover over my class name in my code is single-line, i.e. it looks exactly as if I had written my comment like this:

/// <summary>
/// this comment is on line 1 in the tooltip
/// this comment is on line 2 in the tooltip
/// </summary>

Is this behavior actually possible still in VS2008?

EDIT

gabe pointed out that I have misunderstood what "multiline" means, and I actually need to use <para> or <br> to get my intended effect. I went ahead and used <br> because I want to control where the line breaks occur, i.e.

/// <summary>
/// this comment is on line 1 in the tooltip<br/>
/// this comment is on line 2 in the tooltip<br/>
/// </summary>

When I look at the tooltip for this class in my code, everything still ends up on one line... WTH? Did I do something wrong here?

UPDATE

Ok, I went ahead and tried the <para> tag on each line, and that works. Not sure why <br/> doesn't.

/// <summary>
/// <para>this comment is on line 1 in the tooltip</para>
/// <para>this comment is on line 2 in the tooltip</para>
/// </summary>
Micha Wiedenmann
  • 19,979
  • 21
  • 92
  • 137
Dave
  • 14,618
  • 13
  • 91
  • 145
  • 1
    does anyone know how to preserve whitespace in the XML comments? I'd like to have indentation, if possible. – Dave Mar 30 '10 at 18:52
  • possible duplicate of [Adding line breaks to comments for Intellisense](http://stackoverflow.com/questions/467202/adding-line-breaks-to-comments-for-intellisense) – nawfal Feb 03 '14 at 13:47

3 Answers3

20

Try this 

/// <summary>
/// this comment is on line 1 in the tooltip
/// <para>this comment is on line 2 in the tooltip</para>
/// </summary>
bic
  • 2,201
  • 26
  • 27
19

It sounds like you are confused about what "multi-line" means. A single-line comment ends at the end of the line of source code, and if you want to continue that comment you must put a "///" on the next line. A multi-line comment starts with a "/*" and ends with a "*/" so it can end either on the same line or multiple lines down.

Being "multi-line" says nothing about any how the text within the comment is displayed. To put a line break in an XML comment you must insert a <br/> ("break") or wrap the line in a <para> ("paragraph") tag.

Gabe
  • 84,912
  • 12
  • 139
  • 238
  • thank goodness. thank you for clarifying this, I definitely had a different notion of what "multi-line" was referring to. I'm very glad that I can go back to using /// and I'll start using ! – Dave Mar 30 '10 at 18:41
  • 4
    actually, I do need to use
    since I want to control the line breaks. I went ahead and added
    to the end of every line in my comments, and it still puts everything in the tooltip in one line.     – Dave Mar 30 '10 at 18:45
  • @gabe: do you know how to preserve whitespace? – Dave Mar 30 '10 at 18:50
  • What whitespace do you want to preserve? If it's just spaces you can use ` `. – Gabe Mar 30 '10 at 18:56
  • I have indentation in my comments and wanted them to be visible in the tooltip. – Dave Mar 30 '10 at 19:03
  • Hmm... I tried the tag and it didn't seem to work any differently. I tried replacing with , and also tried to wrap all of the elements with .. no luck. – Dave Mar 30 '10 at 20:13
  • Oh, I see. You want the tooltip to preserve your formatting. Unfortunately that's up to the tooltip, not up to you. You need to have an editor that shows tooltips with the formatting. Have you ever seen a tooltip that includes indentation? – Gabe Mar 30 '10 at 20:53
  • In WPF I have all sorts of crazy tooltips so you never know. ;) – Dave Mar 31 '10 at 00:33
  • 1
      didn't work for me in Visual Studio for intellisence, but the character   seems to do the trick. – Schwarzie2478 Oct 20 '15 at 11:33
3

Add <br/> for line breaks or enclose the paragraphs in <para>...</para>. It's just like XML and HTML, the line break is nothing but whitespace.

Lucero
  • 59,176
  • 9
  • 122
  • 152
  • 1
    I used `
    ` successfully in the past, but then I noticed that tools like Swagger don't understand it - so it seems to be better to go with the ` ... ` approach (although `
    ` is much shorter ...)     – Matt Jun 17 '20 at 15:23