Search code examples
c#commentsxml-comments

Is there any way to preserve white space in C# XML comments?

I'm currently documenting my C# code and would find it useful to include a code block that directly shows how a piece of code should be called. I use the <code> tag that is embedded into the summary:

Code block embedded in C# XML comment summary

While this works in general, I would like to preserve white space (line breaks, indentation). I tried the following so far:

  • I applied the xml:space="preserve" attribute to the <code> tag, but this had no effect at all.
  • I used <br /> to indicate individual new lines (this works as of VS 2019), but I can't insert spaces or tabs. I tried to use &#x20; (for space) and &#x9; (for tab), but the popup wouldn't show those.
  • I tried to use a CDATA section, but the code in between wasn't shown at all.

Br tags work, but space and tab are ignored by the parser

Is there any way to preserve white space in code tags of C# XML comments? Thank you for your help in advance.

Solution

  • Your first XML doc comment is correct. You shouldn't rely on what Intellisense shows you in the tooltips. Intellisense doesn't respect all formatting but it's getting better with each release of VS.

    The newlines and whitespaces in a <code> tag are respected by tools that generate documentation out of the XML comments, such as VSdocman (I am the author) or Sandcastle. The same applies to CDATA. So if you generate, for example, an HTML documentation from your comments, your code block will look fine, with all whitespaces and newlines.

    If you want to see it correctly also in Intellisense, you have to wait, or even better, send a feedback from Visual Studio to the MS team.