CODEWITHSUNDEEP
c#newlinesummary
Theun Arbeider
Theun Arbeider

Reputation: 5419

NewLine in object summary

Greetings

When setting a summary for a property / field / method etc.. is it possible to have a newline in it?

/// <summary>
/// This is line 1
/// This is line 2
/// </summary>
public bool TestLine { get; set; }

When I set this it shows as on mouse over:

bool TestLine
This is line 1 This is line 2

But I want it to show as:

bool TestLine
This is line 1 
This is line 2

I've tried using \n but that doesn't work. Is there any way to get this done?

Upvotes: 159

Views: 76995

Answers (10)

Noah E.
Noah E.

Reputation: 61

As tested on VS2022 today, what I found is that for IntelliSense as most people have said <br/> and \n do nothing, however just adding a <para/> tag instead of <br/> seems to be functionally the same.

/// <summary>
/// Line 1 <para/>
/// Line 2 <para/>
/// Line 3
/// </summary>

Generates an IntelliSense message that reads:

Line 1
Line 2
Line 3

Upvotes: 2

Thomas Cayne
Thomas Cayne

Reputation: 1485

This may be an old thread but I was searching for an anwser while using Visual Studio 2019. I wanted paragraph and lines breaks. The following works well for me:

/// <summary>
/// <para>parameter name="guidType" options:</para>
/// 0 = SequentialAsString<br />
/// 1 = SequentialAsBinary<br />
/// 2 = SequentialAtEnd<br />
/// </summary>

Produces the following:

parameter name="guidType" options:

0 = SequentialAsString
1 = SequentialAsBinary
2 = SequentialAtEnd

Upvotes: 87

sermer
sermer

Reputation: 11

Something I didn't see elsewhere in this thread is that there is a difference between <para></para> and <br></br>.

<para> will add a second newline above the text. So you'll end up with text>empty newline>text.

<br> will only add a single newline. So you'll end up with text>text.

So, IMO, br is better for lists and para is better for breaking up lines.

Upvotes: 1

fdelgado
fdelgado

Reputation: 179

You can use <para /> to add a new line within summary:

/// <summary> 
/// Main comment<para />
/// Line 1<para />
/// Line 2<para />
/// </summary>
public bool TestLine { get; set; }

Looks like:

Main comment
Line 1
Line 2

Best regards!

Upvotes: 17

Dmitry Karpenko
Dmitry Karpenko

Reputation: 592

If you are using Swashbuckle (Swagger Web API integration library) then <para></para> should be replaced with <p></p> and <br/> also could be used.

so the following

    /// <para>
    ///     Flag1, Flag2
    ///     - bool flags, optional.
    /// </para>

becomes

    /// <p>
    ///     Flag1, Flag2<br/>
    ///     - bool flags, optional.
    /// </p>

The issue is already described here: How to add line break to Swashbuckle documentation? - using a special config, domaindrivendev's comment, https://github.com/domaindrivendev/Swashbuckle/issues/258 - on <br/> usage.

Upvotes: 2

PDizzle
PDizzle

Reputation: 181

You can legitimately add para tags, but this actually creates a new paragraph for each new line and the line spacing appears off.
I personally add 1 para around the paragraph and then br tags at the end of the lines I wanted a break on, which preserves decent line spacing:

/// <summary> 
/// <para>Main comment<br /> 
/// Line 1<br />
/// Line 2</para> 
/// </summary>
public bool TestLine { get; set; }

Upvotes: 11

head in the codes
head in the codes

Reputation: 1199

I'm just adding this for anyone using Xamarin Studio like I am. I found that none of the above solutions work for me, but this one did:

/// <summary>
/// Main summarry line.
/// <para></para>
/// <para></para>
/// Your secondary summary
/// </summary>

This gives the following output:

Summary  
Main summary line.

Your secondary summary

Upvotes: 3

Jonathan
Jonathan

Reputation: 361

I would suggest using this formatting if you want multiple lines in the summary without making it complicated. It'll work if you use the <br /> tag after each line. (using it anywhere inside the text will make a new line where the tag is also.)

Although, note that if you have a space after the <br /> tag, you would get an extra space one the next line. So you wanna have the same amount of space on each line, so every row it'll be in a straight line.

/// <summary>
/// This is line 1<br />
/// This is line 2<br />
/// This is line 3<br />
/// </summary>
public bool TestLine { get; set; }

Upvotes: 16

Mitch Wheat
Mitch Wheat

Reputation: 300589

Yes:

/// <summary> 
/// Main comment 
/// <para>Line 1</para> 
/// <para>Line 2</para> 
/// </summary> 
public bool TestLine { get; set; }

Upvotes: 35

YetAnotherUser
YetAnotherUser

Reputation: 9356

You want to use some thing like this 

/// <summary> 
/// Your Main comment 
/// <para>This is line 1</para> 
/// <para>This is line 2</para> 
/// </summary> 
public bool TestLine { get; set; }

Upvotes: 263

Related Questions