Skip to content

fix: preserve jsdoc markdown hard breaks - #800

Merged
dsherret merged 4 commits into
dprint:mainfrom
jmolz:fix-jsdoc-markdown-hard-breaks
Oct 25, 2026
Merged

dsherret merged 4 commits into
dprint:mainfrom
jmolz:fix-jsdoc-markdown-hard-breaks

Conversation

@jmolz

@jmolz jmolz commented Jun 6, 2026 •

Copy link
Copy Markdown
Contributor

Refs denoland/deno#31831.

JSDoc is commonly rendered as Markdown, but the TypeScript formatter currently trims two trailing spaces from non-final JSDoc lines. That removes Markdown hard line breaks. The Markdown plugin normalizes the same input to a backslash hard break, so this applies the same normalization to JSDoc lines while keeping non-JSDoc block comments on the existing trimming behavior.

The regression coverage also guards the main edge cases from the narrower behavior:

  • converts a JSDoc Markdown hard break when another content line follows
  • does not convert a hard break on the last meaningful JSDoc content line
  • does not convert trailing spaces inside a fenced JSDoc code block
  • does not convert hard breaks in non-JSDoc block comments

Tests:

  • cargo test --test specs issue031831
  • cargo test --test specs JSDocComments_All
  • cargo test --test specs CommentBlocks_All
  • cargo test

…lash

Adding a backslash depended on guessing the markdown structure, and
guessing wrong added a visible backslash (ex. at the end of a
paragraph, before a block tag, after a heading, or in example code).
Kept spaces are invisible when they don't do anything, so only a
narrow check is needed:

- keep two spaces when text that isn't a block tag follows on the next line
- don't keep them in fenced code, where a fence only closes with the
  same marker that's at least as long and has nothing after it, or in
  an example without a fence
- don't treat indented lines as code, so nested list items keep them
- look at the next line with a peekable iterator instead of scanning
  every later line, and borrow the lines instead of allocating them
@dsherret

Copy link
Copy Markdown
Member

Warning

This comment is AI generated.

I pushed a change to this PR (e9338e4) that keeps the two trailing spaces of a hard line break instead of converting them to a backslash.

Why

Converting to \ depends on knowing the Markdown structure of the comment. A wrong guess adds a visible backslash. These cases did that before this change:

  • the end of a paragraph (a blank line follows): Summary.\
  • a description line before a block tag: Adds numbers.\ above @param a ...
  • code under an @example without a fence: const x = 1;\
  • headings, *** rules, setext underlines and table rows: # Heading\
  • a line that already ends in a backslash becomes C:\\, which is an escaped backslash with no hard break

Trailing spaces are invisible when they don't do anything, so keeping them where they aren't needed doesn't change how the comment renders. That means the check can stay small instead of trying to parse Markdown.

What it does now

In JSDoc comments only, a line ending in two or more spaces keeps exactly two when:

  • the next line has text and isn't a block tag (@param, @returns, ...), since a hard break does nothing before a blank line or at the end of the description
  • it's not inside a fenced code block, where a fence only closes with the same marker that's at least as long and has nothing after it (so nested fences and fences with an info string work)
  • it's not in an @example without a fence, which is code until the next block tag

Indented lines are no longer treated as code, so nested list items keep their hard breaks. Non-JSDoc block comments are unchanged.

build_lines returns borrowed &str lines again, without allocating a String per line. It checks the next line with a peekable iterator instead of scanning all later lines for each one.

The specs in JSDocComments_All.txt cover the cases above, and the deno issue spec now expects abc instead of abc\.

@dsherret dsherret left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@dsherret
dsherret merged commit 185fa74 into dprint:main Oct 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants