Repository navigation
fix(comments): keep the code lines of an unfenced @example block as they are - #744
Merged
Merged
Conversation
…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>
This was referenced Nov 6, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #735.
What changed
comments --merge-line-commentsreflowed the code inside an@exampletag 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
@exampletag is now kept line for line, the same way a fenced block already is. This applies in two places:buildJsDoc).//merge (mergedJsDocLines). Without this, a// @examplegroup would be joined before the reflow ever saw it.When an example opens and closes:
@exampleon its own line, indented no more than one space. An@example/uipackage name, an@example-footag, an@examplejoined to a sentence, or one inside an indented code sample doesn't open it.@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@mediaand@applystay code too.//group, a bare or captioned@examplestarts 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
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.@examplebodies in JSDoc and in//groups. A separate fuzz run of 40k random blocks found no reordered text and no change on a second pass.mainwith this branch on the 201 files that contain@exampleacross ui-components, node-cli, sassysaint, clubroad, episodia and auth0-thin. 6 files come out differently. In all 6,mainwas merging code lines that this branch keeps as written (useInterval,useIsMountedanduseClickOutsidein ui-hooks, plus 3 files of auth0-spa-js source in auth0-thin'sbuild/folder). None of the 201 files changes on a second pass.🤖 Generated with Claude Code