324

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?

Improve this question
1
  • 13
    It is possible to use <br/> for creating line breaks as of Visual studio 2019. Refer the answer here. Commented Sep 19, 2019 at 0:44

5 Answers 5

Reset to default
456

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>
Improve this answer
Sign up to request clarification or add additional context in comments.

15 Comments

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.
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: stackoverflow.com/questions/7070737/….
Make sure you add the closing </para> tag as well =)
The bad thing about this is that it actually adds one whole blank line, instead of just new line.
So has anyone found a way to actually insert one line instead of two?
|
293

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>

Image of summary appearing in Visual Studio 2019 tooltip, where line breaks are shown where each of the HTML break tags are added in the summary text

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

Improve this answer

6 Comments

Still useful because this question is the top google result for how to add a line break in C# documentation.
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!
See also the text part: learn.microsoft.com/en-us/dotnet/csharp/language-reference/… They also recommend to use <br/> tag now. ;-)
it is not working in case of /* */ comments though. This is the beauty of microsoft products.
The <br/> does not seem to work in XML comments in Visual Studio 2022 now... at least not when it is shown by Swagger.
|
96

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

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

10 Comments

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...
In recent versions of VS <para/> seems to add a blank line, not just a line break.
@IlPADlI, +1 for usage example. Confirmed working on VS 2012 Ultimate Update 5.
VS 2017: blank line added, not simply line break...microsoft sure loves telling us what we want to do...
@Assimilater: You're welcome to write your own OS, IDE and all the other tools from Microsoft you seem displeased with.
|
27

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:

enter image description here

Improve this answer

10 Comments

This is helpful, however &nbsp; does not work, instead use /// <para>&#160;</para>
I personally keep /// <para> </para> in a sticky note. Then it's just copy and paste! (And it works - at least for me)
I don't know why, but copy paste /// <para> </para> does not work at all. /// <para>&#160;</para> works!
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.
Source: I authored this, including most of the presentation style: openstacknetsdk.org/docs-master/html/…
|
7

<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
Improve this answer

1 Comment

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.