From 2690132718b331a2c76531fad7beda8a3436752a Mon Sep 17 00:00:00 2001 From: Arno V Date: Fri, 6 Nov 2026 08:38:26 -0500 Subject: [PATCH 1/5] fix(comments): keep the code lines of an unfenced @example block as they 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 --- .../src/__tests__/lib.example.test.ts | 100 ++++++++++++++++++ packages/comments/src/lib.ts | 33 +++++- 2 files changed, 129 insertions(+), 4 deletions(-) create mode 100644 packages/comments/src/__tests__/lib.example.test.ts diff --git a/packages/comments/src/__tests__/lib.example.test.ts b/packages/comments/src/__tests__/lib.example.test.ts new file mode 100644 index 00000000..9fd1ad05 --- /dev/null +++ b/packages/comments/src/__tests__/lib.example.test.ts @@ -0,0 +1,100 @@ +import { describe, expect, it } from "vitest"; +import { parseAndTransformComments } from "../lib.js"; + +/** + * The body of an @example tag is code: it is kept line for line, like a fenced + * block, up to the next tag (issue 735). + */ +const opts = { width: 80, wrapLineComments: true, mergeLineComments: true }; +const run = (input: string) => + parseAndTransformComments(input, opts).transformed; +const lines = (...l: string[]) => l.join("\n"); + +describe("parseAndTransformComments keeps @example bodies", () => { + it("does not reflow the code lines of an unfenced @example", () => { + const input = lines( + "/**", + " * @example", + " *", + " * const [rightElementRef, rect] = useResizeObserver();", + " *
", + " * Observed: {JSON.stringify(rect)}", + " *
", + " */", + ); + const once = run(input); + expect(once).toBe( + lines( + "/**", + " * @example", + " *", + " * const [rightElementRef, rect] = useResizeObserver();", + " *
", + " * Observed: {JSON.stringify(rect)}", + " *
", + // A block with several paragraphs keeps a trailing blank line. + " *", + " */", + ), + ); + expect(run(once)).toBe(once); + }); + + it("treats lines after the next tag as prose again", () => { + const input = lines( + "/**", + " * @example", + " * foo();", + " * bar()", + " * @returns the cached value", + " * or undefined", + " */", + ); + expect(run(input)).toBe( + lines( + "/**", + " * @example", + " * foo();", + // Code gets no period. + " * bar()", + " * @returns the cached value", + // Prose does. + " * or undefined.", + " */", + ), + ); + }); + + it("keeps a decorator inside the example as code", () => { + const input = lines( + "/**", + " * @example", + " * @Component({ selector: 'app' })", + " * class App {}", + " * new App();", + " */", + ); + expect(run(input)).toBe(input); + }); + + it("keeps the code lines of a merged // @example group", () => { + const input = lines( + "foo();", + "// @example", + "// const a = useTheme();", + "// ", + "bar();", + ); + expect(run(input)).toBe( + lines( + "foo();", + "/**", + " * @example", + " * const a = useTheme();", + " * ", + " */", + "bar();", + ), + ); + }); +}); diff --git a/packages/comments/src/lib.ts b/packages/comments/src/lib.ts index d5aaf648..e1b059ad 100644 --- a/packages/comments/src/lib.ts +++ b/packages/comments/src/lib.ts @@ -299,6 +299,19 @@ function nextFence(open: number, line: string): number { return m[1].length >= open && m[2].trim() === "" ? 0 : open; } +/** + * Whether an @example body is open after `line` (with its indent), given + * whether one was open before it. The body is code, kept line for line like a + * fence, and runs to the next tag. Only an unindented lowercase tag counts, so + * a decorator such as "@Component({" inside the example does not end it. + */ +function exampleAfter(open: boolean, line: string): boolean { + if (!/^@[a-z]/.test(line) || !isTagLine(line)) { + return open; + } + return /^@example(?![\w-])/.test(line); +} + function isVisuallyIndentedCode(line: string): boolean { return /^\s{2,}\S/.test(line); } @@ -429,6 +442,7 @@ function buildJsDoc(indent: string, rawBody: string, width: number): string { let para: string[] = []; // Backtick count of the open code fence, 0 when none. let fence = 0; + let example = false; const prefix = indent + " * "; const avail = Math.max(10, width - prefix.length); @@ -510,6 +524,12 @@ function buildJsDoc(indent: string, rawBody: string, width: number): string { } continue; } + const inExample = example; + example = exampleAfter(example, trimmed); + if (inExample && example) { + out.push(trimmed === "" ? prefix.trimEnd() : prefix + trimmed); + continue; + } if ( trimmed === "" || isListLike(trimmed) || @@ -541,11 +561,11 @@ function buildJsDoc(indent: string, rawBody: string, width: number): string { } flush(); /** - * A fence left open runs to the closing delimiter, and each pass would add one - * more trailing blank line inside it: keep only one. + * A fence or @example left open runs to the closing delimiter, and each pass + * would add one more trailing blank line inside it: keep only one. */ while ( - fence && + (fence || example) && out.length > 1 && out[out.length - 1] === prefix.trimEnd() && out[out.length - 2] === prefix.trimEnd() @@ -725,6 +745,7 @@ function mergedJsDocLines(texts: string[]): string[] { let last = ""; let openList = ""; let fence = 0; + let example = false; const start = (text: string, as: string) => { lines.push([text]); kind = as; @@ -732,10 +753,14 @@ function mergedJsDocLines(texts: string[]): string[] { for (const raw of texts) { const text = normalizeNote(raw.trim()); const next = nextFence(fence, text); + const inExample = example; + if (next === fence && !fence) { + example = exampleAfter(example, raw); + } if (next !== fence) { fence = next; start(text, "fence"); - } else if (fence) { + } else if (fence || (inExample && example)) { start(raw.trimEnd(), "fence"); } else if (text === "") { start("", "blank"); From e401ef7a0336147cc2fe47b1444d7eb0e98989e4 Mon Sep 17 00:00:00 2001 From: Arno V Date: Fri, 6 Nov 2026 10:07:38 -0500 Subject: [PATCH 2/5] fix(comments): open and close @example bodies where a reader would 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 --- packages/comments/README.md | 4 +- .../src/__tests__/lib.example.test.ts | 75 +++++++++++++++++++ .../src/__tests__/realistic-source.ts | 38 ++++++++-- packages/comments/src/lib.ts | 56 +++++++------- 4 files changed, 139 insertions(+), 34 deletions(-) diff --git a/packages/comments/README.md b/packages/comments/README.md index a4197022..90d67602 100644 --- a/packages/comments/README.md +++ b/packages/comments/README.md @@ -4,7 +4,7 @@ CLI tool to reflow, normalize, wrap, and (optionally) merge JavaScript / TypeScr ## Features -- Reflows JSDoc comment blocks to a target max width while preserving code fences, lists, tags, headings, visually‑indented code, runs of spaces and tabs inside inline code, and structured regex / pattern explanation sections. +- Reflows JSDoc comment blocks to a target max width while preserving code fences, the code of an `@example` tag, lists, tags, headings, visually‑indented code, runs of spaces and tabs inside inline code, and structured regex / pattern explanation sections. - Wraps `//` single‑line comments (soft paragraph detection) with smart sentence termination (adds a trailing period only where appropriate). - Optional merging of consecutive `//` lines into a synthetically generated multi‑line JSDoc block (preserves structured groups verbatim; reflows the rest like any JSDoc block, keeping list items and blank-line paragraphs). - NOTE normalization (`note:` → `NOTE:`): each NOTE starts its own line and keeps the rest of its paragraph with it. @@ -126,7 +126,7 @@ interface FileResult { - StyleLint (`stylelint-disable`, `stylelint-enable`) - Coverage tools (`v8 ignore`, `c8 ignore`, `istanbul ignore`) - URLs (`https://...`) -- Preserves fenced code blocks and visually indented code blocks in JSDoc. +- Preserves fenced code blocks, visually indented code blocks and the code of an `@example` tag (up to the next tag) in JSDoc. - Structured explanation groups (regex / pattern walkthroughs) remain line‑stable to avoid unintended semantic changes. - Protects against pathological inputs with maximum indentation and comment body size limits. diff --git a/packages/comments/src/__tests__/lib.example.test.ts b/packages/comments/src/__tests__/lib.example.test.ts index 9fd1ad05..99a999fa 100644 --- a/packages/comments/src/__tests__/lib.example.test.ts +++ b/packages/comments/src/__tests__/lib.example.test.ts @@ -77,6 +77,57 @@ describe("parseAndTransformComments keeps @example bodies", () => { expect(run(input)).toBe(input); }); + it("keeps a lowercase decorator call inside the example as code", () => { + const input = lines( + "/**", + " * @example", + " * @injectable()", + " * class Foo {}", + " * const x = new Foo()", + " */", + ); + expect(run(input)).toBe(input); + }); + + it("opens an example whose tag is indented", () => { + const input = lines( + "/**", + " * @example", + " * const a = 1", + " * const b = 2", + " */", + ); + const once = run(input); + expect(once).toContain(" * const a = 1\n * const b = 2\n"); + expect(run(once)).toBe(once); + }); + + it("does not treat @example-foo as an example", () => { + const input = lines("/**", " * @example-foo", " * a()", " * b()", " */"); + expect(run(input)).toContain(" * a() b()."); + }); + + it("reflows the prose after a fenced example", () => { + const input = lines( + "/**", + " * @example", + " * ```ts", + " * run();", + " * ```", + " *", + " * Any value that is not a number or is less than zero is ignored by the function here", + " */", + ); + const once = run(input); + expect(once).toContain( + lines( + " * Any value that is not a number or is less than zero is ignored by the", + " * function here.", + ), + ); + expect(run(once)).toBe(once); + }); + it("keeps the code lines of a merged // @example group", () => { const input = lines( "foo();", @@ -97,4 +148,28 @@ describe("parseAndTransformComments keeps @example bodies", () => { ), ); }); + + it("keeps the code lines of a merged // group whose @example is indented", () => { + const input = lines( + "foo();", + "// @example", + "// const a = 1", + "// const b = 2", + "bar();", + ); + expect(run(input)).toContain(" * const a = 1\n * const b = 2\n"); + }); + + it("does not open an example for an @example joined to a // sentence", () => { + const input = lines( + "foo();", + "// Documents the", + "// @example tag using `foo", + "// bar` as a literal value", + "bar();", + ); + const once = run(input); + expect(once).toContain("`foo bar`"); + expect(run(once)).toBe(once); + }); }); diff --git a/packages/comments/src/__tests__/realistic-source.ts b/packages/comments/src/__tests__/realistic-source.ts index f0adeba3..9ef589da 100644 --- a/packages/comments/src/__tests__/realistic-source.ts +++ b/packages/comments/src/__tests__/realistic-source.ts @@ -73,13 +73,33 @@ const jsDocBlock = fc.oneof( .map(([h, p]) => [h, ...p]), fc.constant(["```ts", "const value = run();", "```"]), ); -const tags = fc.array( - fc.oneof( - words(1, 8).map((w) => `@param name ${w}`), - words(1, 8).map((w) => `@returns ${w}`), - ), - { maxLength: 2 }, -); +// An @example body: code lines, decorators and blanks, or a closed fence. +const example = fc + .oneof( + fc.array( + fc.constantFrom( + "const value = run();", + " return value;", + "", + "@injectable()", + "@Component({ selector: 'app' })", + "", + ), + { minLength: 1, maxLength: 4 }, + ), + fc.constant(["```ts", "const value = run();", "```"]), + ) + .map((body) => ["@example", ...body]); +const tags = fc + .array( + fc.oneof( + words(1, 8).map((w) => [`@param name ${w}`]), + words(1, 8).map((w) => [`@returns ${w}`]), + example, + ), + { maxLength: 2 }, + ) + .map((t) => t.flat()); const indent = fc.constantFrom("", "\t", "\t\t"); const jsDoc = fc @@ -91,6 +111,9 @@ const jsDoc = fc const lineComment = fc .tuple(indent, handWrapped) .map(([i, ls]) => ls.map((l) => `${i}// ${l}`)); +const exampleComment = fc + .tuple(indent, example) + .map(([i, ls]) => ls.map((l) => `${i}// ${l}`.trimEnd())); const directive = indent.map((i) => [ `${i}// biome-ignore lint/suspicious/noExplicitAny: legacy API`, ]); @@ -103,6 +126,7 @@ export const realisticSource = fc fc.oneof( { weight: 2, arbitrary: jsDoc }, { weight: 2, arbitrary: lineComment }, + exampleComment, directive, { weight: 3, arbitrary: code }, fc.constant([""]), diff --git a/packages/comments/src/lib.ts b/packages/comments/src/lib.ts index e1b059ad..55eedbf3 100644 --- a/packages/comments/src/lib.ts +++ b/packages/comments/src/lib.ts @@ -300,16 +300,21 @@ function nextFence(open: number, line: string): number { } /** - * Whether an @example body is open after `line` (with its indent), given - * whether one was open before it. The body is code, kept line for line like a - * fence, and runs to the next tag. Only an unindented lowercase tag counts, so - * a decorator such as "@Component({" inside the example does not end it. + * Whether `line`, whatever its indent, is an @example tag. Its body is code, + * kept line for line like a fence, until endsExample or a closing fence. */ -function exampleAfter(open: boolean, line: string): boolean { - if (!/^@[a-z]/.test(line) || !isTagLine(line)) { - return open; - } - return /^@example(?![\w-])/.test(line); +function isExampleTag(line: string): boolean { + return /^@example(?![\w-])/.test(line.trim()); +} + +/** + * Whether `line` (with its indent) ends an open @example body: an unindented + * lowercase tag. A decorator inside the example is code, so an indented or + * capitalized one ("@Component({") does not end it, and neither does a call + * ("@injectable()"), since a tag is never followed by "(". + */ +function endsExample(line: string): boolean { + return /^@[a-z][\w-]*(?![\w(/-])/.test(line) && isTagLine(line); } function isVisuallyIndentedCode(line: string): boolean { @@ -507,6 +512,8 @@ function buildJsDoc(indent: string, rawBody: string, width: number): string { const next = nextFence(fence, trimmed); if (next !== fence) { flush(); + // The prose after a fenced example reflows again. + example = example && next !== 0; fence = next; out.push(prefix + trimmed); continue; @@ -524,12 +531,11 @@ function buildJsDoc(indent: string, rawBody: string, width: number): string { } continue; } - const inExample = example; - example = exampleAfter(example, trimmed); - if (inExample && example) { + if (example && !endsExample(trimmed)) { out.push(trimmed === "" ? prefix.trimEnd() : prefix + trimmed); continue; } + example = isExampleTag(trimmed); if ( trimmed === "" || isListLike(trimmed) || @@ -729,14 +735,15 @@ function listKind(text: string): string { * The JSDoc lines for a merged // group, built so the reflow that follows reads * them like a hand-written block. Only prose takes a continuation: the line * after a list item, tag, heading or indented line keeps its own line (and its - * indent), and so do blank lines, NOTE lines and fenced code. An indented line - * after a blank line or prose loses its indent. A list, tag or heading line - * after prose starts its own line only after a sentence end or a colon, or when - * it continues the list open since the last blank line or heading (the same - * kind of item). Otherwise it continues the prose, so a hand-wrapped sentence - * that reaches "@Injectable" or "10." at the start of a line is not split - * there. The last prose line ends with a period, as in 1.1.6, which matters - * when the reflow keeps the block line for line. + * indent), and so do blank lines, NOTE lines, fenced code and the body of an + * example tag on its own line (see isExampleTag). An indented line after a + * blank line or prose loses its indent. A list, tag or heading line after prose + * starts its own line only after a sentence end or a colon, or when it + * continues the list open since the last blank line or heading (the same kind + * of item). Otherwise it continues the prose, so a hand-wrapped sentence that + * reaches "@Injectable" or "10." at the start of a line is not split there. The + * last prose line ends with a period, as in 1.1.6, which matters when the + * reflow keeps the block line for line. */ function mergedJsDocLines(texts: string[]): string[] { const lines: string[][] = []; @@ -753,14 +760,11 @@ function mergedJsDocLines(texts: string[]): string[] { for (const raw of texts) { const text = normalizeNote(raw.trim()); const next = nextFence(fence, text); - const inExample = example; - if (next === fence && !fence) { - example = exampleAfter(example, raw); - } if (next !== fence) { + example = example && next !== 0; fence = next; start(text, "fence"); - } else if (fence || (inExample && example)) { + } else if (fence || (example && !endsExample(raw))) { start(raw.trimEnd(), "fence"); } else if (text === "") { start("", "blank"); @@ -789,6 +793,8 @@ function mergedJsDocLines(texts: string[]): string[] { if (item || heading) { openList = list; } + // Only an @example on its own line opens one, not one joined to prose. + example = isExampleTag(text); } else { lines[lines.length - 1].push(text); } From c3aad613cf05260c03f450dc6858ddd86eb0e4c1 Mon Sep 17 00:00:00 2001 From: Arno V Date: Fri, 6 Nov 2026 10:23:35 -0500 Subject: [PATCH 3/5] fix(comments): keep prose in order around @example and close more gaps 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 --- .../src/__tests__/lib.example.test.ts | 120 ++++++++++++++++++ packages/comments/src/lib.ts | 25 +++- 2 files changed, 138 insertions(+), 7 deletions(-) diff --git a/packages/comments/src/__tests__/lib.example.test.ts b/packages/comments/src/__tests__/lib.example.test.ts index 99a999fa..fdfb18f2 100644 --- a/packages/comments/src/__tests__/lib.example.test.ts +++ b/packages/comments/src/__tests__/lib.example.test.ts @@ -160,6 +160,126 @@ describe("parseAndTransformComments keeps @example bodies", () => { expect(run(input)).toContain(" * const a = 1\n * const b = 2\n"); }); + it("keeps a sentence in order when a line starts with an @example/ package", () => { + const input = lines( + "/**", + " * Import the component from", + " * @example/ui and configure", + " * its props before rendering", + " */", + ); + const once = run(input); + expect(once).toBe( + lines( + "/**", + " * Import the component from @example/ui and configure its props before", + " * rendering.", + " */", + ), + ); + expect(run(once)).toBe(once); + }); + + it("does not open an example for an @example in an indented code sample", () => { + const input = lines( + "/**", + " * Tag a usage sample like this:", + " *", + " * @example", + " * run();", + " *", + " * Then the prose that follows the sample is long enough that it should wrap at eighty columns", + " */", + ); + expect(run(input)).toContain( + lines( + " * Then the prose that follows the sample is long enough that it should wrap at", + " * eighty columns.", + ), + ); + }); + + it("keeps a member decorator call inside the example as code", () => { + const input = lines( + "/**", + " * @example", + " * @di.injectable()", + " * class Foo {}", + " * const x = new Foo()", + " */", + ); + expect(run(input)).toBe(input); + }); + + it("starts a bare // @example on its own line after a summary without a period", () => { + const input = lines( + "foo();", + "// Formats the date for display", + "// @example", + "// formatDate(new Date())", + "// formatDate(other)", + "bar();", + ); + const once = run(input); + expect(once).toBe( + lines( + "foo();", + "/**", + " * Formats the date for display.", + " * @example", + " * formatDate(new Date())", + " * formatDate(other)", + " */", + "bar();", + ), + ); + expect(run(once)).toBe(once); + }); + + it("ends a merged // example at the next tag", () => { + const input = lines( + "foo();", + "// @example", + "// foo()", + "// @returns the count", + "// of a sentence that reaches", + "// 10. items", + "bar();", + ); + const once = run(input); + expect(once).toBe( + lines( + "foo();", + "/**", + " * @example", + " * foo()", + " * @returns the count", + " * of a sentence that reaches 10. items.", + " */", + "bar();", + ), + ); + expect(run(once)).toBe(once); + }); + + it("reflows the prose after a fenced example in a merged // group", () => { + const input = lines( + "foo();", + "// @example", + "// ```ts", + "// x", + "// ```", + "// A sentence that reaches", + "// 10. items", + "bar();", + ); + const once = run(input); + expect(once).toContain( + " * ```\n * A sentence that reaches 10. items.\n */", + ); + expect(run(once)).toBe(once); + }); + it("does not open an example for an @example joined to a // sentence", () => { const input = lines( "foo();", diff --git a/packages/comments/src/lib.ts b/packages/comments/src/lib.ts index 55eedbf3..3832f6a4 100644 --- a/packages/comments/src/lib.ts +++ b/packages/comments/src/lib.ts @@ -300,21 +300,28 @@ function nextFence(open: number, line: string): number { } /** - * Whether `line`, whatever its indent, is an @example tag. Its body is code, - * kept line for line like a fence, until endsExample or a closing fence. + * Whether `line` (with its indent) is an @example tag, so not a package such as + * "@example/ui", and not indented like code (one stray space is fine). Its body + * is code, kept line for line like a fence, until endsExample or a closing + * fence. */ function isExampleTag(line: string): boolean { - return /^@example(?![\w-])/.test(line.trim()); + return ( + !/^\s{2}/.test(line) && + isTagLine(line) && + /^@example(?![\w-])/.test(line.trim()) + ); } /** * Whether `line` (with its indent) ends an open @example body: an unindented * lowercase tag. A decorator inside the example is code, so an indented or - * capitalized one ("@Component({") does not end it, and neither does a call - * ("@injectable()"), since a tag is never followed by "(". + * capitalized one ("@Component({") does not end it, and neither does a call or + * a member ("@injectable()", "@di.injectable()"), since a tag is never followed + * by "(" or ".". */ function endsExample(line: string): boolean { - return /^@[a-z][\w-]*(?![\w(/-])/.test(line) && isTagLine(line); + return /^@[a-z][\w-]*(?![\w(./-])/.test(line) && isTagLine(line); } function isVisuallyIndentedCode(line: string): boolean { @@ -532,6 +539,8 @@ function buildJsDoc(indent: string, rawBody: string, width: number): string { continue; } if (example && !endsExample(trimmed)) { + // No line of the example may overtake prose still waiting in `para`. + flush(); out.push(trimmed === "" ? prefix.trimEnd() : prefix + trimmed); continue; } @@ -780,6 +789,8 @@ function mergedJsDocLines(texts: string[]): string[] { if ( kind !== "prose" || note || + // A bare @example never continues a sentence, even one without a period. + text === "@example" || ((item || heading) && (endsSentence(last) || /:$/.test(last) || @@ -794,7 +805,7 @@ function mergedJsDocLines(texts: string[]): string[] { openList = list; } // Only an @example on its own line opens one, not one joined to prose. - example = isExampleTag(text); + example = isExampleTag(raw); } else { lines[lines.length - 1].push(text); } From b84ee42ad54c61c64377ed886d87980aefda0d7c Mon Sep 17 00:00:00 2001 From: Arno V Date: Fri, 6 Nov 2026 12:04:07 -0500 Subject: [PATCH 4/5] fix(comments): end an @example only at a real tag, and keep a captioned one apart MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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()" and a Vue "@click="save"" stay code. - "// @example …" 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 --- packages/comments/README.md | 2 +- .../src/__tests__/lib.example.test.ts | 67 +++++++++++++++++++ packages/comments/src/lib.ts | 18 ++--- 3 files changed, 78 insertions(+), 9 deletions(-) diff --git a/packages/comments/README.md b/packages/comments/README.md index 90d67602..4c65fa49 100644 --- a/packages/comments/README.md +++ b/packages/comments/README.md @@ -126,7 +126,7 @@ interface FileResult { - StyleLint (`stylelint-disable`, `stylelint-enable`) - Coverage tools (`v8 ignore`, `c8 ignore`, `istanbul ignore`) - URLs (`https://...`) -- Preserves fenced code blocks, visually indented code blocks and the code of an `@example` tag (up to the next tag) in JSDoc. +- Preserves fenced code blocks, visually indented code blocks and the code of an `@example` tag (up to the next tag or closing fence) in JSDoc. - Structured explanation groups (regex / pattern walkthroughs) remain line‑stable to avoid unintended semantic changes. - Protects against pathological inputs with maximum indentation and comment body size limits. diff --git a/packages/comments/src/__tests__/lib.example.test.ts b/packages/comments/src/__tests__/lib.example.test.ts index fdfb18f2..48049d12 100644 --- a/packages/comments/src/__tests__/lib.example.test.ts +++ b/packages/comments/src/__tests__/lib.example.test.ts @@ -280,6 +280,73 @@ describe("parseAndTransformComments keeps @example bodies", () => { expect(run(once)).toBe(once); }); + it("ends an example at a tag indented like its opener", () => { + const input = lines( + "/**", + " * @example", + " * foo()", + " * @returns the cached value", + " * or undefined", + " */", + ); + const once = run(input); + expect(once).toContain(" * or undefined.\n"); + expect(run(once)).toBe(once); + }); + + it.each([ + ["a generic decorator", "@injectable()"], + ["a template attribute", '@click="save"'], + ])("keeps %s inside the example as code", (_, decorator) => { + const input = lines( + "/**", + " * @example", + ` * ${decorator}`, + " * class Foo {}", + " * const x = new Foo()", + " */", + ); + expect(run(input)).toBe(input); + }); + + it("keeps CSS at-rules inside the example as code", () => { + const input = lines( + "/**", + " * @example", + " * @media (min-width: 40rem)", + " * .a { color: red }", + " * @apply px-2", + " * .b {}", + " */", + ); + expect(run(input)).toBe(input); + }); + + it("starts a captioned // @example on its own line after a summary without a period", () => { + const input = lines( + "foo();", + "// Usage", + "// @example Basic", + "// const a = 1", + "// const b = 2", + "bar();", + ); + const once = run(input); + expect(once).toBe( + lines( + "foo();", + "/**", + " * Usage.", + " * @example Basic", + " * const a = 1", + " * const b = 2", + " */", + "bar();", + ), + ); + expect(run(once)).toBe(once); + }); + it("does not open an example for an @example joined to a // sentence", () => { const input = lines( "foo();", diff --git a/packages/comments/src/lib.ts b/packages/comments/src/lib.ts index 3832f6a4..bcb5e7d0 100644 --- a/packages/comments/src/lib.ts +++ b/packages/comments/src/lib.ts @@ -314,14 +314,15 @@ function isExampleTag(line: string): boolean { } /** - * Whether `line` (with its indent) ends an open @example body: an unindented - * lowercase tag. A decorator inside the example is code, so an indented or - * capitalized one ("@Component({") does not end it, and neither does a call or - * a member ("@injectable()", "@di.injectable()"), since a tag is never followed - * by "(" or ".". + * Whether `line` (with its indent) ends an open @example body: a lowercase tag, + * indented no more than the tag that opened it (see isExampleTag). A decorator + * inside the example is code, so an indented or capitalized one + * ("@Component({") does not end it, and neither does one followed by anything + * but a space, "{" or the end of the line ("@injectable()", "@di.injectable()", + * "@click="save""). */ function endsExample(line: string): boolean { - return /^@[a-z][\w-]*(?![\w(./-])/.test(line) && isTagLine(line); + return /^\s?@[a-z][\w-]*(?=[\s{]|$)/.test(line) && isTagLine(line); } function isVisuallyIndentedCode(line: string): boolean { @@ -789,8 +790,9 @@ function mergedJsDocLines(texts: string[]): string[] { if ( kind !== "prose" || note || - // A bare @example never continues a sentence, even one without a period. - text === "@example" || + // An @example alone or with a caption never continues a sentence, even + // one without a period. + /^@example(?:$|\s+)/.test(text) || ((item || heading) && (endsSentence(last) || /:$/.test(last) || From 4a906b6141fe787d322cd43633d9b6c81951cdc1 Mon Sep 17 00:00:00 2001 From: Arno V Date: Fri, 6 Nov 2026 12:26:15 -0500 Subject: [PATCH 5/5] fix(comments): end an @example at a tag followed by a colon - "@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 --- .../src/__tests__/lib.example.test.ts | 33 ++++++++++++++++++- packages/comments/src/lib.ts | 14 ++++---- 2 files changed, 39 insertions(+), 8 deletions(-) diff --git a/packages/comments/src/__tests__/lib.example.test.ts b/packages/comments/src/__tests__/lib.example.test.ts index 48049d12..85a25984 100644 --- a/packages/comments/src/__tests__/lib.example.test.ts +++ b/packages/comments/src/__tests__/lib.example.test.ts @@ -290,10 +290,41 @@ describe("parseAndTransformComments keeps @example bodies", () => { " */", ); const once = run(input); - expect(once).toContain(" * or undefined.\n"); + expect(once).toBe( + lines( + "/**", + " * @example", + " * foo()", + " * @returns the cached value", + " * or undefined.", + " */", + ), + ); expect(run(once)).toBe(once); }); + it("ends an example at a tag followed by a colon", () => { + const input = lines( + "/**", + " * @example", + " * run()", + " * @default: 5", + " * the default value used", + " * when nothing is set", + " */", + ); + expect(run(input)).toBe( + lines( + "/**", + " * @example", + " * run()", + " * @default: 5", + " * the default value used when nothing is set.", + " */", + ), + ); + }); + it.each([ ["a generic decorator", "@injectable()"], ["a template attribute", '@click="save"'], diff --git a/packages/comments/src/lib.ts b/packages/comments/src/lib.ts index bcb5e7d0..4516e1b4 100644 --- a/packages/comments/src/lib.ts +++ b/packages/comments/src/lib.ts @@ -314,15 +314,15 @@ function isExampleTag(line: string): boolean { } /** - * Whether `line` (with its indent) ends an open @example body: a lowercase tag, - * indented no more than the tag that opened it (see isExampleTag). A decorator - * inside the example is code, so an indented or capitalized one - * ("@Component({") does not end it, and neither does one followed by anything - * but a space, "{" or the end of the line ("@injectable()", "@di.injectable()", - * "@click="save""). + * Whether `line` (with its indent) ends an open @example body: a lowercase tag + * indented by at most one space, like the tags isExampleTag accepts. A + * decorator inside the example is code, so an indented or capitalized one + * (`@Component({`) does not end it, and neither does one followed by anything + * but a space, "{", ":" or the end of the line (`@injectable()`, + * `@di.injectable()`, `@click="save"`). */ function endsExample(line: string): boolean { - return /^\s?@[a-z][\w-]*(?=[\s{]|$)/.test(line) && isTagLine(line); + return /^\s?@[a-z][\w-]*(?=[\s{:]|$)/.test(line) && isTagLine(line); } function isVisuallyIndentedCode(line: string): boolean {