How to add a line break in C# .NET documentation

Question

This should be waaaay easier...

I want to add a "coded" line break to the XML documentation in my code

/// <summary>
/// Get a human-readable variant of the SQL WHERE statement of the search element. &lt;br/&gt;
/// Rather than return SQL, this method returns a string with icon-tokens, which 
/// could be used to represent the search in a condensed pictogram format.
/// </summary>

As you can see, I found some answers that demonstrated adding < and > brackets. Interestingly, the good 'ol < br/ > line break does not create a line break in the Intellisense popup.

I find this annoying...

Any suggestions?

Mitten

It is possible to use <br/> for creating line breaks as of Visual studio 2019. Refer the answer here. – Lick

Answer 1

You can use a <para /> tag to produce a paragraph break or you can wrap text in <para></para> tags as a way to group the text and add the blank line after it, but there is no equivalent to <br /> or anything like that. (Which according to this old MS forum post is by design.) You can get the list of available tags in this documentation article from MS. Documenting your code

Example (based on original OP sample):

/// <summary>
/// <para>Get a human-readable variant of the SQL WHERE statement of the search element.</para>
/// Rather than return SQL, this method returns a string with icon-tokens, which 
/// could be used to represent the search in a condensed pictogram format.
/// </summary>

Dingdong

Aha! Now were cooking! Thanks! This has been bothering me for a long time now... I saw the para option listed, but assumed it was a "paramater" shortcut. – Mitten

Did not work for me. Using VB.NET on VS 2010, tried with and without Powertools' colorized parameter option, <para> tags are ignored, and everything is mixed into a single line in Intellisense. Found this question, where Hans explained the problem: #7071237. – Hoskins

Make sure you add the closing </para> tag as well =) – Maniple

@Maniple - I actually had it as <para /> when I originally wrote this post. – Dingdong

doesn't work on VS2013 as well. All the text within <para> tag is ignored – Mendelism

<para /> before text or text put inside <para> ... </para> is drawn on the new line. Tested with VS2015. – Unsocial

The bad thing about this is that it actually adds one whole blank line, instead of just new line. – Celestine

So has anyone found a way to actually insert one line instead of two? – Gormandize

This adds a blank line also, and have 237 votes up? There is no way to just line break without adding a blank line? – Teodora

@Teodora - No, and according to an old MS forum post, that is by design. – Dingdong

@ALazyDoe - No, and as far as I understand, this is "by design" as the intention of "summary" comments was to be a single line and "remarks" were for longer bits of information. – Dingdong

@Celestine - I believe the behavior of this has varied between versions of the IDE, but according to the docs and and old MS forum post, the lack of a <br /> or some other line break equivalent is by design. I answered this back in 2011 based on the behavior of VS 2010. – Dingdong

IMO guys from MS probably have done it just to remind us to have short and useful comments(not tons of sentences describing functionality). And of course for users of your class/interface/functions/enum/etc. it is important to have basic and useful information. So I am using <para>NOTE: ...</para> in case of I want to add some additional information to the basic description. By the way it was interesting for me and tested with VS2017 and VS2019 - <br/> is NOT working. For more descriptive information you can use <remarks> – Heliogravure

@MiroslavHristov - It was definitely by design and you may be correct in the reasoning behind it, but whatever the case is, you can achieve a line break (albeit with a newline) using <para> and you should use <remarks> for larger descriptions. BTW and in an unrelated side note - I also live in Sofia :) здрасти! – Dingdong

@Dingdong - I do not like using <para />(<para>&nbsp;</para> or similar techniques) for "achieving" new lines - just because to have new lines. In my (XMLDoc)comments I am using <para /> only for some NOTES(or any additional information to main description). For larger description I am using <remarks>. Поздрави ;) – Heliogravure

Answer 2

As of Visual Studio 2019, use <br/> for newlines in comments.

Example:

/// <summary>
/// This is a comment.<br/>
/// This is another comment <br/>
/// This is a long comment so i want it to continue <br/> on another line.
/// </summary>

Notice that there is no extra line added when we use <br/> instead of <para>.

Lick

Still useful because this question is the top google result for how to add a line break in C# documentation. – Animato

I'd upvote this if it worked in Visual Studio Code as well as in Visual Studio 2019. Perhaps I missed a setting, but <br/> does nothing for me in VSC. Thanks for the VS tip though! – Styles

See also the text part: learn.microsoft.com/en-us/dotnet/csharp/language-reference/… They also recommend to use <br/> tag now. ;-) – Unciform

it is not working in case of /* */ comments though. This is the beauty of microsoft products. – Landtag

Answer 3

This is my usage, like <br/> , it's working :)

/// <summary>
/// Value: 0/1/2
/// <para/>0 foo,
/// <para/>1 bar,
/// <para/>2 other
/// </summary>

Revegetate

Why is this answer downvoted? It works, and seems to be a much better solution than using <para>&#160;</para>, <para>&nbsp;</para> or the invisible character... – Anticlerical

This works for newlines, but won't insert a blank line between things like the other options do. – Overstretch

@Yushatak, actually, it does insert a blank line in C#, but not in F#. Don't know why there's a difference. – Pudendum

@Pudendum Not on my copy of VS2013, 12.0.40629.0 REL - maybe it varies between versions of the IDE. – Overstretch

In recent versions of VS <para/> seems to add a blank line, not just a line break. – Anticlerical

Yes, <para/> make a reduplicate blank line. But up to now can't find other way to make line-break in tool tip document. – Revegetate

@IlPADlI, +1 for usage example. Confirmed working on VS 2012 Ultimate Update 5. – Flushing

VS 2017: blank line added, not simply line break...microsoft sure loves telling us what we want to do... – Lennox

@Assimilater: You're welcome to write your own OS, IDE and all the other tools from Microsoft you seem displeased with. – Overture

Yep, this works in VS 2019 although I much prefer putting the <para/> at the end of the line, similar to how it's typically done with <br />'s – Brain

Answer 4

Add a <para> tag with a special char in it, the 255 char, or invisible char.

/// <summary>
/// Some text
/// <para>   </para>
/// More text
/// </summary>
/// <param name="str">Some string</param>
public void SomeMethod(string str) { }

It will work like this:

Itself

This is helpful, however   does not work, instead use /// <para>&#160;</para> – Monstrosity

I personally keep /// <para> </para> in a sticky note. Then it's just copy and paste! (And it works - at least for me) – Itself

I don't know why, but copy paste /// <para> </para> does not work at all. /// <para>&#160;</para> works! – Whirlabout

Rather than use the <para> tag between blocks of text, you should use the <para> tag around all paragraphs except the first in the <summary> element. For the <typeparam>, <param>, <value>, <exception>, and <returns> elements, use them around all paragraphs if you have more than one (optional if you only have one for these elements). For all other block elements (including <note> inside of another block element), use <para> tags around all paragraphs, even if you only have one. – Carrion

Source: I authored this, including most of the presentation style: openstacknetsdk.org/docs-master/html/… – Carrion

@280Z28 That is some nice information, thanks for pointing it out. This is just a demo to show the actual empty line when pressing Ctrl+Space in VS, but feel free to add more comments to improve it :) – Itself

It works but correct usage is like this. It helps if you ever integrate with an automatic documentation system in future. /// <summary> /// <para>Some text</para> /// <para>More text</para> /// </summary> /// <param name="str">Some string</param> – Cordelia

As of December 2022, /// <para>&#160;</para> does NOT work to insert a blank line in VS 2019 (at least for me), nor does copy/pasting the non-breaking space character. Right now resorting to putting a dot character for a "blank" line: /// <para>.</para> – Tranquillity

@Tranquillity at least with resharper it still works with VS2022 – Itself

+1 using /// <para>&#160;</para> works in C# when using JetBrains Rider 2023.1.2, especially inside a <code> element when you want blank lines between the code sample in the block. – Jarietta

Answer 5

<br></br> and <br /> do not seem to work, and sometimes it isn't really about making the <para> sentences separate as much as the desire to have a blank line for concern separation. I am mentioning this here because this question seems to be to parent to many closed questions of this nature.

The only thing I found to work was

<para>&#160;</para>

For example

/// <summary>
///     <para>
///         "This sentence shows up when the type is hovered"
///     </para>
///     <para>&#160;</para>
///     <para>int PrimaryKey</para>
///     <para>&#160;</para>
///     <para>virtual Relation Relation</para>
/// </summary>

Results in

"This sentence shows up when the type is hovered"

int PrimaryKey

virtual Relation Relation

Venial

+1 as of 2023, using /// <para>&#160;</para> works in C# when using JetBrains Rider 2023.1.2, especially inside a <code> element when you want blank lines between the code sample in the block. – Jarietta