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 line break does not create a line break in the Intellisense popup.

I find this annoying...

Any suggestions?

It is possible to use
for creating line breaks as of Visual studio 2019. Refer the answer [here](https://stackoverflow.com/a/57734549/12001603). — 23bl, Sep 19 '19 at 00:44

pstrjds · Accepted Answer · 2018-11-27T16:38:14.497

352

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

edited Nov 27 '18 at 16:38

answered Sep 02 '11 at 04:04

pstrjds

15,103
6
48
60

6

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. – Tinkerer_CardTracker Sep 02 '11 at 04:23
2

Did not work for me. Using VB.NET on VS 2010, tried with and without Powertools' colorized parameter option, `` tags are ignored, and everything is mixed into a single line in Intellisense. Found this question, where Hans explained the problem: http://stackoverflow.com/questions/7070737/multiline-xml-comments-in-vb-net-and-visual-studio-intellisense. – Neolisk Nov 25 '13 at 16:26
1

Make sure you add the closing tag as well =) – link64 Nov 24 '14 at 01:01
1

@link64 - I actually had it as `` when I originally wrote this post. – pstrjds Nov 24 '14 at 04:45
doesn't work on VS2013 as well. All the text within tag is ignored – Naili Jul 20 '15 at 19:03
1

`` before text or text put inside ` ... ` is drawn on the new line. Tested with VS2015. – Sinatr Jul 31 '15 at 12:01
89

The bad thing about this is that it actually adds one whole blank line, instead of just new line. – Devid May 16 '16 at 12:21
6

So has anyone found a way to actually insert one line instead of two? – Feb 20 '18 at 13:13
This adds a blank line also, and have 237 votes up? There is no way to just line break without adding a blank line? – Pedro77 Jul 03 '18 at 21:59
1

@Pedro77 - No, and according to an old MS forum post, that is by design. – pstrjds Jul 04 '18 at 06:38
1

@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. – pstrjds Jul 04 '18 at 06:46
@Devid - 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 `
` or some other line break equivalent is by design. I answered this back in 2011 based on the behavior of VS 2010. – pstrjds Jul 04 '18 at 06:51
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 NOTE: ... 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 -
is NOT working. For more descriptive information you can use – Miroslav Hristov Aug 04 '19 at 09:32
@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 `` and you should use `` for larger descriptions. BTW and in an unrelated side note - I also live in Sofia :) здрасти! – pstrjds Aug 04 '19 at 14:08
@pstrjds - I do not like using ( or similar techniques) for "achieving" new lines - just because to have new lines. In my (XMLDoc)comments I am using only for some NOTES(or any additional information to main description). For larger description I am using . Поздрави ;) – Miroslav Hristov Aug 06 '19 at 13:03

score 83 · Answer 2 · edited Apr 03 '20 at 00:35

83

This is my usage, like   , it's working :)

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

edited Apr 03 '20 at 00:35

Pang

8,605
144
77
113

answered Sep 02 '14 at 02:56

IlPADlI

1,657
16
20

8

Why is this answer downvoted? It works, and seems to be a much better solution than using ` `, ` ` or the invisible character... – Dinei Oct 23 '14 at 14:30
This works for newlines, but won't insert a blank line between things like the other options do. – Yushatak Sep 12 '16 at 16:55
@Yushatak, actually, it does insert a blank line in C#, but not in F#. Don't know why there's a difference. – Abel Sep 19 '16 at 20:12
@Abel Not on my copy of VS2013, 12.0.40629.0 REL - maybe it varies between versions of the IDE. – Yushatak Sep 20 '16 at 12:32
19

In recent versions of VS `` seems to add a blank line, not just a line break. – Dinei Jan 02 '17 at 16:45
Yes, make a reduplicate blank line. But up to now can't find other way to make line-break in *tool tip* document. – IlPADlI Jan 02 '17 at 20:44
2

@IlPADlI, +1 for usage example. Confirmed working on VS 2012 Ultimate Update 5. – Dennis T --Reinstate Monica-- May 11 '17 at 21:42
9

VS 2017: blank line added, not simply line break...microsoft sure loves telling us what we want to do... – Assimilater Jul 06 '17 at 19:25
1

@Assimilater: You're welcome to write your own OS, IDE and all the other tools from Microsoft you seem displeased with. – Mircea Ion Jun 17 '19 at 22:31
Yep, this works in VS 2019 although I much prefer putting the `` at the _end_ of the line, similar to how it's typically done with `
`'s – Jay Allen Jul 23 '19 at 21:15

score 76 · Answer 3 · edited Apr 03 '20 at 00:34

76

As of Visual Studio 2019, use   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   instead of <para>.

edited Apr 03 '20 at 00:34

Pang

8,605
144
77
113

answered Aug 31 '19 at 01:17

23bl

761
3
4

7

Still useful because this question is the top google result for how to add a line break in C# documentation. – Dan Sep 13 '19 at 17:53
This answer needs to be higher, or accepted as the correct answer, it is hidden below 2 answers telling you to use ``. – Joel Mar 23 '21 at 01:39
I'd upvote this if it worked in Visual Studio Code as well as in Visual Studio 2019. Perhaps I missed a setting, but
does nothing for me in VSC. Thanks for the VS tip though! – IdusOrtus May 20 '21 at 13:59

score 26 · Answer 4 · answered Apr 10 '13 at 12:03

26

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

answered Apr 10 '13 at 12:03

Joel

6,735
4
46
54

9

This is helpful, however ` ` does not work, instead use `/// ` – Robert H Apr 10 '14 at 18:18
1

I personally keep `/// ` in a sticky note. Then it's just copy and paste! (And it works - at least for me) – Joel Apr 10 '14 at 18:47
2

I don't know why, but copy paste `/// ` does not work at all. `/// ` works! – wenqiang May 09 '14 at 20:21
9

Rather than use the `` tag between blocks of text, you should use the `` tag around all paragraphs *except* the first in the `
` element. For the ``, ``, ``, ``, and `` 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 `` inside of another block element), use `` tags around all paragraphs, even if you only have one.
– Sam Harwell Sep 02 '14 at 03:27
1

Source: I authored this, including most of the presentation style: http://openstacknetsdk.org/docs-master/html/362f6481-64dd-4f21-9e71-1d157b5dc745.htm – Sam Harwell Sep 02 '14 at 03:28
@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 :) – Joel Sep 02 '14 at 10:17
It works but correct usage is like this. It helps if you ever integrate with an automatic documentation system in future. `///
/// Some text /// More text ///
/// Some string` – Guney Ozsan Nov 08 '18 at 11:38

score 3 · Answer 5 · answered Aug 04 '14 at 22:07

  and   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

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

5 Answers5

Linked

Related