Introduction

In C#, API documentation comments are XML, not plain text. That means pressing Enter in a /// block does not automatically create the kind of visible line break or paragraph break you may expect in IntelliSense or generated docs. To control formatting, use XML documentation tags such as para and, when necessary, br/.

Use para for Real Paragraph Breaks

If you want the documentation to render as separate paragraphs, para is the best tool. It is explicit, valid XML, and supported by the standard C# documentation pipeline.

1/// <summary>
2/// Reads application settings from disk.
3/// <para>
4/// Call this during startup before building the main window.
5/// </para>
6/// <para>
7/// Throws <see cref="InvalidOperationException"/> when the settings file is missing.
8/// </para>
9/// </summary>
10public void LoadSettings()
11{
12}

With this form, IntelliSense and many documentation generators render the two para blocks as distinct paragraphs. That is clearer than relying on blank comment lines and hoping the consumer preserves them.

Use br/ for a Forced Line Break

Sometimes you do not want a new paragraph. You just want the next sentence on a new line inside the same description. In that case, use br/.

1/// <summary>
2/// Connects to the server.<br/>
3/// Retries automatically up to three times.
4/// </summary>
5public void Connect()
6{
7}

Use this sparingly. Paragraphs are usually more readable than manual line breaks, especially in IDE tooltips where width and wrapping vary.

Why Plain Newlines Are Not Enough

Documentation comments are compiled into an XML file when the project enables XML documentation output. The compiler preserves the XML structure, not the visual layout of your source file. A blank /// line may improve source readability for humans, but it does not always become a rendered break in consumers of the generated XML.

That is why tags matter. They encode the meaning of the break rather than depending on whitespace. Once you think of doc comments as XML content, the behavior becomes predictable.

A More Complete Example

You can combine paragraphs, references, and code markers to keep documentation readable without sacrificing structure.

1/// <summary>
2/// Saves the current document.
3/// <para>
4/// Returns immediately when there are no pending changes.
5/// </para>
6/// <para>
7/// Use <see cref="SaveAsync"/> if the operation may take noticeable time.
8/// </para>
9/// </summary>
10/// <remarks>
11/// The file path is validated before the write starts.
12/// </remarks>
13public void Save()
14{
15}

This style works well because each piece of information has a purpose: the summary explains the API, the paragraphs separate behavior notes, and see links connect related members.

Common Pitfalls

The most common mistake is treating documentation comments like console output strings. Environment.NewLine and escape sequences such as \\n are for runtime strings, not for XML doc comment layout.

Another frequent error is writing invalid XML. For example, br without the closing slash is not valid XML in this context. If the comment is malformed, the compiler can warn and documentation tools may skip or misread the content.

Developers also overuse manual line breaks where para would communicate intent better. A paragraph says that a new conceptual block starts. A line break only says the text should continue on the next rendered line.

Finally, remember that different tools render documentation differently. IntelliSense, DocFX, Sandcastle-style generators, and custom pipelines may not look identical. Sticking to well-known XML tags gives you the best chance of consistent output.

Summary

• C# documentation comments are XML, not plain text.
• Use para for paragraph breaks in IntelliSense and generated docs.
• Use br/ only when you need a forced line break inside one paragraph.
• Do not use runtime string newline techniques for XML documentation comments.
• Keep the XML valid so the compiler and documentation tools can parse it reliably.