diff --git a/packages/comments/README.md b/packages/comments/README.md index a4197022..4c65fa49 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 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 new file mode 100644 index 00000000..85a25984 --- /dev/null +++ b/packages/comments/src/__tests__/lib.example.test.ts @@ -0,0 +1,393 @@ +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 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();", + "// @example", + "// const a = useTheme();", + "// ", + "bar();", + ); + expect(run(input)).toBe( + lines( + "foo();", + "/**", + " * @example", + " * const a = useTheme();", + " * ", + " */", + "bar();", + ), + ); + }); + + 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("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("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).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"'], + ])("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();", + "// 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 d5aaf648..4516e1b4 100644 --- a/packages/comments/src/lib.ts +++ b/packages/comments/src/lib.ts @@ -299,6 +299,32 @@ function nextFence(open: number, line: string): number { return m[1].length >= open && m[2].trim() === "" ? 0 : open; } +/** + * 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 ( + !/^\s{2}/.test(line) && + isTagLine(line) && + /^@example(?![\w-])/.test(line.trim()) + ); +} + +/** + * 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); +} + function isVisuallyIndentedCode(line: string): boolean { return /^\s{2,}\S/.test(line); } @@ -429,6 +455,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); @@ -493,6 +520,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; @@ -510,6 +539,13 @@ 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; + } + example = isExampleTag(trimmed); if ( trimmed === "" || isListLike(trimmed) || @@ -541,11 +577,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() @@ -709,14 +745,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[][] = []; @@ -725,6 +762,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; @@ -733,9 +771,10 @@ function mergedJsDocLines(texts: string[]): string[] { const text = normalizeNote(raw.trim()); const next = nextFence(fence, text); if (next !== fence) { + example = example && next !== 0; fence = next; start(text, "fence"); - } else if (fence) { + } else if (fence || (example && !endsExample(raw))) { start(raw.trimEnd(), "fence"); } else if (text === "") { start("", "blank"); @@ -751,6 +790,9 @@ function mergedJsDocLines(texts: string[]): string[] { if ( kind !== "prose" || note || + // 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) || @@ -764,6 +806,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(raw); } else { lines[lines.length - 1].push(text); }