Adding line breaks to c comments for Intellisense

Intellisense

line breaks

comments

duplicate

Adding line breaks to c comments for Intellisense

Master System Design with Codemia

Enhance your system design skills with over 120 practice problems, detailed solutions, and hands-on exercises.

Start Practicing Learn More

Introduction

To add line breaks in C# XML documentation comments that display in IntelliSense, use the <para> tag to create paragraph breaks or   for line breaks. Standard newlines in XML comments are collapsed into a single space by IntelliSense. The <para> tag is the officially supported approach and works reliably across Visual Studio versions. The   tag works in some versions but is not part of the official XML documentation spec.

Basic XML Comment Structure

csharp

1/// <summary>
2/// This is a single-line summary.
3/// </summary>
4public void SimpleMethod() { }
5
6/// <summary>
7/// This spans multiple lines in the source code
8/// but IntelliSense displays it as ONE line because
9/// XML collapses whitespace and newlines.
10/// </summary>
11public void CollapsedMethod() { }

In the second example, IntelliSense shows: "This spans multiple lines in the source code but IntelliSense displays it as ONE line because XML collapses whitespace and newlines."

Using <para> for Paragraph Breaks

csharp

1/// <summary>
2/// Calculates the total price including tax.
3/// <para>
4/// The tax rate is determined by the customer's shipping address.
5/// International orders use a flat 10% rate.
6/// </para>
7/// <para>
8/// Returns -1 if the cart is empty.
9/// </para>
10/// </summary>
11/// <param name="cartId">The shopping cart identifier.</param>
12/// <returns>Total price with tax, or -1 for empty carts.</returns>
13public decimal CalculateTotal(int cartId) { }

IntelliSense renders each <para> block as a separate paragraph with spacing between them.

Using for Line Breaks

csharp

1/// <summary>
2/// Supported formats:<br/>
3/// - JSON<br/>
4/// - XML<br/>
5/// - CSV<br/>
6/// - YAML
7/// </summary>
8public void ParseFile(string path) { }

Note:   works in Visual Studio but is not part of the official C# XML documentation tags. Some documentation generators (Sandcastle, DocFX) may ignore it.

Using <list> for Structured Content

For bullet points or numbered lists, use the <list> tag:

csharp

1/// <summary>
2/// Validates the input data against the following rules:
3/// <list type="bullet">
4/// <item><description>Name must not be empty</description></item>
5/// <item><description>Age must be between 0 and 150</description></item>
6/// <item><description>Email must contain @ symbol</description></item>
7/// </list>
8/// </summary>
9public bool Validate(UserInput input) { }
10
11/// <summary>
12/// Processing steps:
13/// <list type="number">
14/// <item><description>Parse the input file</description></item>
15/// <item><description>Validate all records</description></item>
16/// <item><description>Transform to output format</description></item>
17/// <item><description>Write to destination</description></item>
18/// </list>
19/// </summary>
20public void ProcessFile(string path) { }

Using <remarks> for Extended Documentation

csharp

1/// <summary>
2/// Sends an email notification to the specified recipient.
3/// </summary>
4/// <remarks>
5/// <para>
6/// This method uses SMTP to send emails. The SMTP server
7/// configuration is read from appsettings.json.
8/// </para>
9/// <para>
10/// Rate limiting applies: maximum 100 emails per minute.
11/// Exceeding this limit throws <see cref="RateLimitException"/>.
12/// </para>
13/// </remarks>
14/// <param name="recipient">Email address of the recipient.</param>
15/// <param name="subject">Email subject line.</param>
16/// <param name="body">HTML body content.</param>
17/// <exception cref="RateLimitException">Thrown when rate limit is exceeded.</exception>
18public void SendEmail(string recipient, string subject, string body) { }

Using <code> and <c> for Code in Comments

csharp

1/// <summary>
2/// Parses a date string in ISO 8601 format.
3/// <para>
4/// Usage:
5/// <code>
6/// var date = ParseDate("2024-01-15");
7/// var dateTime = ParseDate("2024-01-15T10:30:00Z");
8/// </code>
9/// </para>
10/// <para>
11/// Use <c>null</c> to indicate no date filter.
12/// </para>
13/// </summary>
14public DateTime ParseDate(string input) { }

<c> renders inline code. <code> renders a code block (preserves whitespace and line breaks).

Complete Example

csharp

1/// <summary>
2/// Connects to the database and executes a health check.
3/// <para>
4/// This method tests the connection by running a simple
5/// <c>SELECT 1</c> query against the configured database.
6/// </para>
7/// </summary>
8/// <remarks>
9/// <para>
10/// Connection parameters are read from the connection string
11/// named "DefaultConnection" in appsettings.json.
12/// </para>
13/// <para>
14/// Timeout behavior:
15/// </para>
16/// <list type="bullet">
17/// <item><description>Connection timeout: 30 seconds</description></item>
18/// <item><description>Command timeout: 10 seconds</description></item>
19/// <item><description>Retry attempts: 3 with exponential backoff</description></item>
20/// </list>
21/// </remarks>
22/// <returns>
23/// <c>true</c> if the database is reachable; <c>false</c> otherwise.
24/// </returns>
25/// <exception cref="InvalidOperationException">
26/// Thrown when the connection string is not configured.
27/// </exception>
28public bool CheckDatabaseHealth() { }

Common Pitfalls

Expecting newlines to render in IntelliSense: XML collapses all whitespace (spaces, tabs, newlines) into a single space. Line breaks in the source code /// comments do not produce line breaks in IntelliSense. You must use <para> or   tags explicitly.
Using   for portable documentation:   works in Visual Studio IntelliSense but is not part of the official C# XML documentation tags. Documentation generators like DocFX, Sandcastle, or NuGet package documentation may ignore or strip   tags. Use <para> for maximum compatibility.
Nesting <para> inside <para>: The <para> tag creates a paragraph block. Nesting one <para> inside another produces invalid XML documentation. Use sibling <para> tags at the same level for multiple paragraphs.
Forgetting the closing tag on <list> items: <list> requires <item> and <description> child elements with proper closing tags. Malformed XML silently breaks IntelliSense tooltips — the entire summary may stop displaying. Check the Error List window for XML comment warnings.
Using &, <, > without escaping: XML comments are parsed as XML. Literal < must be <, > must be >, and & must be &. Writing /// Returns true if a < b breaks the XML parser. Use <c>a < b</c> or rephrase to avoid special characters.

Summary

Use <para> tags to create paragraph breaks in XML documentation comments — standard newlines are collapsed
Use <list type="bullet"> or <list type="number"> for structured bullet/numbered lists in IntelliSense
Use <c> for inline code and <code> for multi-line code blocks (preserves formatting)
Place extended documentation in <remarks> to separate the brief summary from detailed notes
Escape XML special characters (<, >, &) in documentation comments to avoid parse errors

Adding line breaks to c comments for Intellisense

Master System Design with Codemia

Introduction

Basic XML Comment Structure

Using <para> for Paragraph Breaks

Using <br/> for Line Breaks

Using <list> for Structured Content

Using <remarks> for Extended Documentation

Using <code> and <c> for Code in Comments

Complete Example

Common Pitfalls

Summary