Skip to content

fix(comments): keep the code lines of an unfenced @example block as they are - #744

Merged
aversini merged 5 commits into
mainfrom
claude/issue-735-validation-ec8a9a
Nov 6, 2026
Merged

aversini merged 5 commits into
mainfrom
claude/issue-735-validation-ec8a9a

Conversation

@aversini

@aversini aversini commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes #735.

What changed

comments --merge-line-comments reflowed the code inside an @example tag as if it were prose. For example, useResizeObserver<HTMLDivElement>(); and <div ref={rightElementRef}> got joined onto one line and then rewrapped.

The body of an @example tag is now kept line for line, the same way a fenced block already is. This applies in two places:

  • The JSDoc reflow (buildJsDoc).
  • The // merge (mergedJsDocLines). Without this, a // @example group would be joined before the reflow ever saw it.

When an example opens and closes:

  • It opens only at an @example on its own line, indented no more than one space. An @example/ui package name, an @example-foo tag, an @example joined to a sentence, or one inside an indented code sample doesn't open it.
  • It ends at the next lowercase tag, indented like the opener (@returns, @param, a second @example), or at a closing fence. A tag is followed by a space, {, : or the end of the line. So decorators and template attributes stay code: @Component({, @injectable(), @di.injectable(), @injectable<Foo>(), @click="save". CSS at-rules such as @media and @apply stay code too.
  • Prose waiting before the example is written out first, so no code line overtakes it. The prose after a fenced example reflows again.
  • In a // group, a bare or captioned @example starts its own line, even after a summary with no period.

The trailing * line in the issue's output is not part of this fix. A block with several paragraphs keeps a trailing blank line, which is existing, tested behavior.

Verification

  • 22 tests in lib.example.test.ts. Each one fails on the commit before its fix. Reverting any single rule turns at least one test red. All 139 tests in the package pass.
  • The property-test generator now produces @example bodies in JSDoc and in // groups. A separate fuzz run of 40k random blocks found no reordered text and no change on a second pass.
  • I compared main with this branch on the 201 files that contain @example across ui-components, node-cli, sassysaint, clubroad, episodia and auth0-thin. 6 files come out differently. In all 6, main was merging code lines that this branch keeps as written (useInterval, useIsMounted and useClickOutside in ui-hooks, plus 3 files of auth0-spa-js source in auth0-thin's build/ folder). None of the 201 files changes on a second pass.

🤖 Generated with Claude Code

aversini and others added 5 commits November 6, 2026 08:38
…hey are

The body of an @example tag is code, so the JSDoc reflow and the // merge now
keep it line for line, like a fenced block, up to the next lowercase tag. A
decorator such as @component inside the example does not end it.

Fixes #735

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review fixes for the @example handling:

- Only an @example that starts its own line opens an example, so one that a
  // sentence wraps onto no longer splits inline code there.
- An indented @example opens one too, in a JSDoc block and in a // group.
- A decorator call such as @Injectable() stays inside the example: a tag is
  never followed by "(".
- A fence that closes inside an example ends it, so the prose after a fenced
  example reflows again.
- The property test now generates @example blocks and // groups.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Second round of review fixes:

- An @example opens an example only when it is a real tag, so a sentence
  that wraps onto a package such as @example/ui no longer gets reordered,
  and buffered prose is flushed before any example line.
- An @example in an indented code sample no longer opens one, so the prose
  after the sample reflows again.
- A member decorator such as @di.injectable() stays inside the example.
- A bare // @example starts its own line even after a summary without a
  period.
- Tests for a tag or a fence ending an example in a merged // group.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ed one apart

- A tag indented like the @example that opened the block now ends it, so a
  block written with two spaces after the star reflows its prose again.
- A decorator ends the example only when it reads like a tag: followed by a
  space, "{" or the end of the line. "@Injectable<Foo>()" and a Vue
  "@click="save"" stay code.
- "// @example <caption>…</caption>" after a summary with no period starts its
  own line, as a bare "// @example" already did.
- Tests for each, plus one for CSS at-rules inside an example.
- README: example code runs up to the next tag or closing fence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- "@default: 5" ends the example again, as it did before the previous commit,
  so the prose after it reflows.
- The endsExample comment now states the real indent rule: at most one space.
- The indent test compares the whole output.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@aversini
aversini merged commit 908f20c into main Nov 6, 2026
4 checks passed
@aversini
aversini deleted the claude/issue-735-validation-ec8a9a branch November 6, 2026 17:56
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.

comments: --merge-line-comments reflows code lines in an unfenced @example block

1 participant