CODEWITHSUNDEEP
c#visual-studio-2008commentsmultilinexml-comments
Dave
Dave

Reputation: 15016

XML multiline comments in C# - what am I doing wrong?

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>

Upvotes: 32

Views: 17792

Answers (4)

Fables Alive
Fables Alive

Reputation: 2808

surround with para tag and use < b r / > tag not < b r > its not standard indeed.

/// <summary>
/// <para>
/// This is First hint line <br/> dont forget slash : ) cuz this is second hint line <br/>
/// Third Line
/// Third Line Continues : ) <br/> oh! this is the last line ;)
/// </para>
/// </summary>
public string[] tagsToIgnore;

enter image description here

Upvotes: 0

Gabe
Gabe

Reputation: 86708

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.

Upvotes: 22

bic
bic

Reputation: 2281

Try this 

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

Upvotes: 20

Lucero
Lucero

Reputation: 60190

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.

Upvotes: 3

Related Questions