From 024fd52208afad925cb025e124b43e45f3c7b8a9 Mon Sep 17 00:00:00 2001 From: Arno V Date: Fri, 6 Nov 2026 13:12:56 -0500 Subject: [PATCH 1/6] fix(comments): end an @example only at a known JSDoc tag - An @example body now ends only at a known JSDoc, TSDoc, TypeScript or TypeDoc block tag (jsdoc-tags.ts), compared case-insensitively. A lowercase decorator such as "@observable price = 0" or "@computed get total()" stays code. "import", "function" and "mixin" are left out because they are also CSS, Sass or TypeScript lines. - "// @example Basic usage" (a capitalized title) after a summary with no period starts its own line, as a bare or captioned @example already did. - New tests in lib.example-tags.test.ts; the property-test generator now produces titled examples and a lowercase decorator. Closes #745. Co-Authored-By: Claude Opus 5.5 --- .../src/__tests__/lib.example-tags.test.ts | 81 ++++++++++++ .../src/__tests__/realistic-source.ts | 12 +- packages/comments/src/jsdoc-tags.ts | 120 ++++++++++++++++++ packages/comments/src/lib.ts | 20 +-- 4 files changed, 223 insertions(+), 10 deletions(-) create mode 100644 packages/comments/src/__tests__/lib.example-tags.test.ts create mode 100644 packages/comments/src/jsdoc-tags.ts diff --git a/packages/comments/src/__tests__/lib.example-tags.test.ts b/packages/comments/src/__tests__/lib.example-tags.test.ts new file mode 100644 index 0000000..f89b8cc --- /dev/null +++ b/packages/comments/src/__tests__/lib.example-tags.test.ts @@ -0,0 +1,81 @@ +import { describe, expect, it } from "vitest"; +import { JSDOC_BLOCK_TAGS } from "../jsdoc-tags.js"; +import { parseAndTransformComments } from "../lib.js"; + +/** + * Only a known block tag ends an @example body, and a titled // @example starts + * its own line (issue 745). + */ +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 ends @example bodies at known tags", () => { + it.each([ + ["@observable price = 0"], + ["@computed get total() {"], + ['@import "theme.css";'], + ])("keeps %s inside the example as code", (code) => { + const input = lines( + "/**", + " * @example", + ` * ${code}`, + " * const cart = new Cart()", + " */", + ); + expect(run(input)).toBe(input); + }); + + it("ends an example at a camelCase TSDoc tag", () => { + const input = lines( + "/**", + " * @example", + " * foo()", + " * @typeParam T the item type", + " * of the list", + " */", + ); + expect(run(input)).toBe( + lines( + "/**", + " * @example", + " * foo()", + " * @typeParam T the item type", + " * of the list.", + " */", + ), + ); + }); + + it("starts a titled // @example on its own line after a summary without a period", () => { + const input = lines( + "foo();", + "// Usage", + "// @example Basic usage", + "// const a = 1", + "// const b = 2", + "bar();", + ); + const once = run(input); + expect(once).toBe( + lines( + "foo();", + "/**", + " * Usage.", + " * @example Basic usage", + " * const a = 1", + " * const b = 2", + " */", + "bar();", + ), + ); + expect(run(once)).toBe(once); + }); + + it("stores every tag name lowercased, as endsExample compares them", () => { + for (const tag of JSDOC_BLOCK_TAGS) { + expect(tag).toBe(tag.toLowerCase()); + } + }); +}); diff --git a/packages/comments/src/__tests__/realistic-source.ts b/packages/comments/src/__tests__/realistic-source.ts index 9ef589d..f46176a 100644 --- a/packages/comments/src/__tests__/realistic-source.ts +++ b/packages/comments/src/__tests__/realistic-source.ts @@ -73,7 +73,10 @@ const jsDocBlock = fc.oneof( .map(([h, p]) => [h, ...p]), fc.constant(["```ts", "const value = run();", "```"]), ); -// An @example body: code lines, decorators and blanks, or a closed fence. +/** + * An @example, with or without a title, then code lines, decorators and blanks, + * or a closed fence. + */ const example = fc .oneof( fc.array( @@ -83,13 +86,18 @@ const example = fc "", "@injectable()", "@Component({ selector: 'app' })", + "@observable price = 0", "", ), { minLength: 1, maxLength: 4 }, ), fc.constant(["```ts", "const value = run();", "```"]), ) - .map((body) => ["@example", ...body]); + .chain((body) => + fc + .constantFrom("@example", "@example Basic usage") + .map((tag) => [tag, ...body]), + ); const tags = fc .array( fc.oneof( diff --git a/packages/comments/src/jsdoc-tags.ts b/packages/comments/src/jsdoc-tags.ts new file mode 100644 index 0000000..8c1341a --- /dev/null +++ b/packages/comments/src/jsdoc-tags.ts @@ -0,0 +1,120 @@ +/** + * Block tag names from JSDoc, TSDoc, TypeScript and TypeDoc, lowercased. Only + * one of these ends an @example body, so a decorator in the example's code + * ("@observable price = 0", "@computed get total()") stays code. + * + * "import", "function" and "mixin" are left out on purpose: they are also CSS, + * Sass or TypeScript lines that an example's code is likely to hold. + * + */ +export const JSDOC_BLOCK_TAGS = new Set([ + // JSDoc. + "abstract", + "access", + "alias", + "arg", + "argument", + "async", + "augments", + "author", + "borrows", + "callback", + "class", + "classdesc", + "const", + "constant", + "constructor", + "constructs", + "copyright", + "default", + "defaultvalue", + "deprecated", + "desc", + "description", + "emits", + "enum", + "event", + "example", + "exception", + "exports", + "extends", + "external", + "file", + "fileoverview", + "fires", + "func", + "generator", + "global", + "hideconstructor", + "host", + "ignore", + "implements", + "inheritdoc", + "inner", + "instance", + "interface", + "kind", + "lends", + "license", + "listens", + "member", + "memberof", + "method", + "mixes", + "module", + "name", + "namespace", + "override", + "overview", + "package", + "param", + "private", + "prop", + "property", + "protected", + "public", + "readonly", + "requires", + "return", + "returns", + "see", + "since", + "static", + "summary", + "this", + "throws", + "todo", + "tutorial", + "type", + "typedef", + "var", + "variation", + "version", + "virtual", + "yield", + "yields", + // TSDoc. + "alpha", + "beta", + "decorator", + "eventproperty", + "experimental", + "internal", + "label", + "packagedocumentation", + "privateremarks", + "remarks", + "sealed", + "typeparam", + // TypeScript and TypeDoc. + "category", + "expand", + "group", + "hidden", + "overload", + "satisfies", + "template", + // Common outside the standards. + "note", + "warning", +]); diff --git a/packages/comments/src/lib.ts b/packages/comments/src/lib.ts index 4516e1b..125f96e 100644 --- a/packages/comments/src/lib.ts +++ b/packages/comments/src/lib.ts @@ -1,4 +1,5 @@ import { Logger } from "@node-cli/logger"; +import { JSDOC_BLOCK_TAGS } from "./jsdoc-tags.js"; export const logger = new Logger({ boring: process.env.NODE_ENV === "test" }); @@ -314,15 +315,17 @@ function isExampleTag(line: string): boolean { } /** - * 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 + * Whether `line` (with its indent) ends an open @example body: a known block + * tag (see JSDOC_BLOCK_TAGS), lowercase and indented by at most one space, like + * the tags isExampleTag accepts. A decorator inside the example is code, so an + * unknown one (`@observable price = 0`), 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()`, + * but a space, "{", ":" or the end of the line (`@property()`, * `@di.injectable()`, `@click="save"`). */ function endsExample(line: string): boolean { - return /^\s?@[a-z][\w-]*(?=[\s{:]|$)/.test(line) && isTagLine(line); + const tag = /^\s?@([a-z][\w-]*)(?=[\s{:]|$)/.exec(line); + return tag !== null && JSDOC_BLOCK_TAGS.has(tag[1].toLowerCase()); } function isVisuallyIndentedCode(line: string): boolean { @@ -790,9 +793,10 @@ 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) || + // An @example alone, with a caption or with a capitalized title ("Basic + // usage") never continues a sentence, even one without a period. A + // lowercase word after it ("@example tag") may be prose. + /^@example(?:$|\s+|\s+[A-Z])/.test(text) || ((item || heading) && (endsSentence(last) || /:$/.test(last) || From d474cf986cbf43e9539abfea5b2d8b66b3d33a96 Mon Sep 17 00:00:00 2001 From: Arno V Date: Fri, 6 Nov 2026 14:39:02 -0500 Subject: [PATCH 2/6] fix(comments): drop the titled // @example rule and complete the tag list - A capitalized word after "// @example" no longer starts a new line: it could not tell a title from a sentence that wraps at the tag ("an @example JSDoc tag"), which then got a period mid-sentence. Titled // examples behave as they do on main. - JSDOC_BLOCK_TAGS gains the TypeDoc, Closure Compiler, custom elements manifest and Doxygen block tags, plus @examples, @preserve, @usageNotes and @publicApi, so the prose after them reflows again. Each has a test. - Tests for the Sass @function/@mixin exclusions, a second @example, an unknown decorator and a camelCase tag in // examples, in a new lib.example-state.test.ts; the word-order property test now generates @example, @returns and @observable. - README and comments match the new rule. Co-Authored-By: Claude Opus 5.5 --- packages/comments/README.md | 2 +- .../src/__tests__/lib.example-state.test.ts | 98 +++++++++++++++++++ .../src/__tests__/lib.example-tags.test.ts | 93 +++++++++++++++--- .../src/__tests__/lib.property.test.ts | 3 + packages/comments/src/jsdoc-tags.ts | 63 +++++++++++- packages/comments/src/lib.ts | 18 ++-- 6 files changed, 253 insertions(+), 24 deletions(-) create mode 100644 packages/comments/src/__tests__/lib.example-state.test.ts diff --git a/packages/comments/README.md b/packages/comments/README.md index 4c65fa4..f6868f4 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 or closing fence) in JSDoc. +- Preserves fenced code blocks, visually indented code blocks and the code of an `@example` tag (up to the next known JSDoc 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-state.test.ts b/packages/comments/src/__tests__/lib.example-state.test.ts new file mode 100644 index 0000000..14d9a1c --- /dev/null +++ b/packages/comments/src/__tests__/lib.example-state.test.ts @@ -0,0 +1,98 @@ +import { describe, expect, it } from "vitest"; +import { parseAndTransformComments } from "../lib.js"; + +/** + * How an open @example body moves between states in both comment forms: a + * second @example, an unknown decorator and a camelCase tag (issue 745). + */ +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 moves through @example states", () => { + it("opens a second @example while one is open", () => { + const input = lines( + "/**", + " * @example First", + " * a()", + " * @example Second", + " * @observable b = 0", + " */", + ); + expect(run(input)).toBe(input); + }); + + it("opens a second // @example while one is open", () => { + const input = lines( + "foo();", + "// Summary.", + "// @example First", + "// a()", + "// @example Second", + "// b()", + "bar();", + ); + const once = run(input); + expect(once).toBe( + lines( + "foo();", + "/**", + " * Summary.", + " * @example First", + " * a()", + " * @example Second", + " * b()", + " */", + "bar();", + ), + ); + expect(run(once)).toBe(once); + }); + + it("keeps an unknown decorator inside a // example as code", () => { + const input = lines( + "foo();", + "// @example", + "// @observable price = 0", + "// const cart = new Cart()", + "bar();", + ); + expect(run(input)).toBe( + lines( + "foo();", + "/**", + " * @example", + " * @observable price = 0", + " * const cart = new Cart()", + " */", + "bar();", + ), + ); + }); + + it("ends a // example at a camelCase TSDoc tag", () => { + const input = lines( + "foo();", + "// @example", + "// foo()", + "// @typeParam T the item type", + "// of the list", + "bar();", + ); + const once = run(input); + expect(once).toBe( + lines( + "foo();", + "/**", + " * @example", + " * foo()", + " * @typeParam T the item type", + " * of the list.", + " */", + "bar();", + ), + ); + expect(run(once)).toBe(once); + }); +}); diff --git a/packages/comments/src/__tests__/lib.example-tags.test.ts b/packages/comments/src/__tests__/lib.example-tags.test.ts index f89b8cc..b078c4a 100644 --- a/packages/comments/src/__tests__/lib.example-tags.test.ts +++ b/packages/comments/src/__tests__/lib.example-tags.test.ts @@ -3,8 +3,7 @@ import { JSDOC_BLOCK_TAGS } from "../jsdoc-tags.js"; import { parseAndTransformComments } from "../lib.js"; /** - * Only a known block tag ends an @example body, and a titled // @example starts - * its own line (issue 745). + * Only a known block tag ends an @example body (issue 745). */ const opts = { width: 80, wrapLineComments: true, mergeLineComments: true }; const run = (input: string) => @@ -16,6 +15,9 @@ describe("parseAndTransformComments ends @example bodies at known tags", () => { ["@observable price = 0"], ["@computed get total() {"], ['@import "theme.css";'], + // Left out of JSDOC_BLOCK_TAGS on purpose, so Sass stays code. + ["@function rem($px) {"], + ["@mixin center {"], ])("keeps %s inside the example as code", (code) => { const input = lines( "/**", @@ -48,13 +50,11 @@ describe("parseAndTransformComments ends @example bodies at known tags", () => { ); }); - it("starts a titled // @example on its own line after a summary without a period", () => { + it("keeps a // sentence that wraps at a capitalized word after @example in one piece", () => { const input = lines( "foo();", - "// Usage", - "// @example Basic usage", - "// const a = 1", - "// const b = 2", + "// The reflow keeps the body of an", + "// @example JSDoc tag line for line, and joins the prose after it", "bar();", ); const once = run(input); @@ -62,10 +62,8 @@ describe("parseAndTransformComments ends @example bodies at known tags", () => { lines( "foo();", "/**", - " * Usage.", - " * @example Basic usage", - " * const a = 1", - " * const b = 2", + " * The reflow keeps the body of an @example JSDoc tag line for line, and joins", + " * the prose after it.", " */", "bar();", ), @@ -73,6 +71,79 @@ describe("parseAndTransformComments ends @example bodies at known tags", () => { expect(run(once)).toBe(once); }); + // TypeDoc, Closure, custom-elements manifest, Doxygen and other block tags. + it.each([ + "categoryDescription", + "groupDescription", + "document", + "sortStrategy", + "inline", + "expandType", + "inlineType", + "mergeModuleWith", + "preventExpand", + "preventInline", + "primaryExport", + "useDeclaredType", + "showCategories", + "hideCategories", + "showGroups", + "hideGroups", + "disableGroups", + "final", + "export", + "define", + "suppress", + "nocollapse", + "nosideeffects", + "record", + "struct", + "dict", + "unrestricted", + "externs", + "modifies", + "slot", + "csspart", + "cssprop", + "cssproperty", + "cssstate", + "attr", + "attribute", + "element", + "tag", + "tagname", + "brief", + "details", + "tparam", + "retval", + "pre", + "post", + "bug", + "examples", + "preserve", + "usageNotes", + "publicApi", + ])("ends an example at @%s", (tag) => { + const input = lines( + "/**", + " * @example", + " * foo()", + ` * @${tag} the value`, + " * and the rest", + " */", + ); + expect(run(input)).toBe( + lines( + "/**", + " * @example", + " * foo()", + ` * @${tag} the value`, + " * and the rest.", + " */", + ), + ); + }); + it("stores every tag name lowercased, as endsExample compares them", () => { for (const tag of JSDOC_BLOCK_TAGS) { expect(tag).toBe(tag.toLowerCase()); diff --git a/packages/comments/src/__tests__/lib.property.test.ts b/packages/comments/src/__tests__/lib.property.test.ts index 0ae6e3c..f5c2b0d 100644 --- a/packages/comments/src/__tests__/lib.property.test.ts +++ b/packages/comments/src/__tests__/lib.property.test.ts @@ -16,6 +16,9 @@ const token = fc.oneof( "note:", "aNOTE:", "@param", + "@returns", + "@example", + "@observable", "@auth0/auth0-react", "@media", "-", diff --git a/packages/comments/src/jsdoc-tags.ts b/packages/comments/src/jsdoc-tags.ts index 8c1341a..385b795 100644 --- a/packages/comments/src/jsdoc-tags.ts +++ b/packages/comments/src/jsdoc-tags.ts @@ -1,10 +1,14 @@ /** - * Block tag names from JSDoc, TSDoc, TypeScript and TypeDoc, lowercased. Only - * one of these ends an @example body, so a decorator in the example's code - * ("@observable price = 0", "@computed get total()") stays code. + * Block tag names from JSDoc, TSDoc, TypeScript, TypeDoc, Closure Compiler, the + * custom elements manifest and Doxygen, lowercased. Only one of these ends + * an @example body, so a decorator in the example's code whose name is not a + * tag ("@observable price = 0", "@computed get total()") stays code, while one + * named like a tag ("@readonly") still ends it. * * "import", "function" and "mixin" are left out on purpose: they are also CSS, * Sass or TypeScript lines that an example's code is likely to hold. + * "property", "namespace" and "return" are CSS or Sass at-rules too, but stay + * in as tags that doc comments use far more often. * */ export const JSDOC_BLOCK_TAGS = new Set([ @@ -108,13 +112,66 @@ export const JSDOC_BLOCK_TAGS = new Set([ "typeparam", // TypeScript and TypeDoc. "category", + "categorydescription", + "disablegroups", + "document", "expand", + "expandtype", "group", + "groupdescription", "hidden", + "hidecategories", + "hidegroups", + "inline", + "inlinetype", + "mergemodulewith", "overload", + "preventexpand", + "preventinline", + "primaryexport", "satisfies", + "showcategories", + "showgroups", + "sortstrategy", "template", + "usedeclaredtype", + // Closure Compiler. + "define", + "dict", + "export", + "externs", + "final", + "modifies", + "nocollapse", + "nosideeffects", + "record", + "struct", + "suppress", + "unrestricted", + // Custom elements manifest (web components, Lit). + "attr", + "attribute", + "csspart", + "cssprop", + "cssproperty", + "cssstate", + "element", + "slot", + "tag", + "tagname", + // Doxygen. + "brief", + "bug", + "details", + "post", + "pre", + "retval", + "tparam", // Common outside the standards. + "examples", "note", + "preserve", + "publicapi", + "usagenotes", "warning", ]); diff --git a/packages/comments/src/lib.ts b/packages/comments/src/lib.ts index 125f96e..40e6e1b 100644 --- a/packages/comments/src/lib.ts +++ b/packages/comments/src/lib.ts @@ -316,11 +316,11 @@ function isExampleTag(line: string): boolean { /** * Whether `line` (with its indent) ends an open @example body: a known block - * tag (see JSDOC_BLOCK_TAGS), lowercase and indented by at most one space, like - * the tags isExampleTag accepts. A decorator inside the example is code, so an - * unknown one (`@observable price = 0`), 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 (`@property()`, + * tag (see JSDOC_BLOCK_TAGS), starting lowercase, indented by at most one + * space, like the tags isExampleTag accepts. A decorator inside the example is + * code, so an unknown one (`@observable price = 0`), 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 (`@property()`, * `@di.injectable()`, `@click="save"`). */ function endsExample(line: string): boolean { @@ -793,10 +793,10 @@ function mergedJsDocLines(texts: string[]): string[] { if ( kind !== "prose" || note || - // An @example alone, with a caption or with a capitalized title ("Basic - // usage") never continues a sentence, even one without a period. A - // lowercase word after it ("@example tag") may be prose. - /^@example(?:$|\s+|\s+[A-Z])/.test(text) || + // An @example alone or with a caption never continues a sentence, even + // one without a period. Any other word after it may be prose that wraps + // there ("an @example JSDoc tag"), so a plain title is not told apart. + /^@example(?:$|\s+)/.test(text) || ((item || heading) && (endsSentence(last) || /:$/.test(last) || From e89088c027c104fb6a7b8e2aea64ed7d31f93f32 Mon Sep 17 00:00:00 2001 From: Arno V Date: Fri, 6 Nov 2026 15:11:11 -0500 Subject: [PATCH 3/6] fix(comments): end an @example at the JSDoc forms of @function, @mixin and @import - "@function" and "@mixin", alone or with one name, and TypeScript's "@import {" or "@import *" end an example again, as on main. Their Sass and CSS forms ("@function rem($px) {", "@mixin center {", "@import "x.css";") stay code. - More tags end an example: @customElement, Closure's @implicitCast, @noalias and @nocompile, and the @jsx and test-environment pragmas. - Tests: a decorator call named like a tag, a capitalized tag and an indented tag stay code in both comment forms; the second-@example test can now fail; every listed name must read as a tag in prose too, so the list never takes in a CSS at-rule. Co-Authored-By: Claude Opus 5.5 --- .../src/__tests__/lib.example-state.test.ts | 36 +++++++++++- .../src/__tests__/lib.example-tags.test.ts | 56 +++++++++++++++++++ packages/comments/src/jsdoc-tags.ts | 27 ++++++--- packages/comments/src/lib.ts | 14 ++++- 4 files changed, 123 insertions(+), 10 deletions(-) diff --git a/packages/comments/src/__tests__/lib.example-state.test.ts b/packages/comments/src/__tests__/lib.example-state.test.ts index 14d9a1c..1d1879e 100644 --- a/packages/comments/src/__tests__/lib.example-state.test.ts +++ b/packages/comments/src/__tests__/lib.example-state.test.ts @@ -17,12 +17,46 @@ describe("parseAndTransformComments moves through @example states", () => { " * @example First", " * a()", " * @example Second", - " * @observable b = 0", + // A plain code line: it would get a period if the example closed here. + " * b()", + " * @observable c = 0", " */", ); expect(run(input)).toBe(input); }); + it.each([ + // A tag name used as a call, a capitalized one, and one indented as code. + ["@property() name = ''"], + ["@Override"], + [" @returns x"], + ])("keeps %s inside the example as code", (code) => { + const input = lines( + "/**", + " * @example", + " * foo()", + ` * ${code}`, + " * y()", + " */", + ); + expect(run(input)).toBe(input); + }); + + it.each([["@property() name = ''"], ["@Override"], [" @returns x"]])( + "keeps %s inside a // example as code", + (code) => { + const input = lines( + "foo();", + "// @example", + "// foo()", + `// ${code}`, + "// y()", + "bar();", + ); + expect(run(input)).toContain(` * foo()\n * ${code}\n * y()\n */`); + }, + ); + it("opens a second // @example while one is open", () => { const input = lines( "foo();", diff --git a/packages/comments/src/__tests__/lib.example-tags.test.ts b/packages/comments/src/__tests__/lib.example-tags.test.ts index b078c4a..3a7cf7e 100644 --- a/packages/comments/src/__tests__/lib.example-tags.test.ts +++ b/packages/comments/src/__tests__/lib.example-tags.test.ts @@ -15,6 +15,7 @@ describe("parseAndTransformComments ends @example bodies at known tags", () => { ["@observable price = 0"], ["@computed get total() {"], ['@import "theme.css";'], + ['@import url("print.css") print;'], // Left out of JSDOC_BLOCK_TAGS on purpose, so Sass stays code. ["@function rem($px) {"], ["@mixin center {"], @@ -123,6 +124,16 @@ describe("parseAndTransformComments ends @example bodies at known tags", () => { "preserve", "usageNotes", "publicApi", + "implicitCast", + "noalias", + "nocompile", + "customElement", + "jest-environment", + "jsx", + "jsxFrag", + "jsxImportSource", + "jsxRuntime", + "vitest-environment", ])("ends an example at @%s", (tag) => { const input = lines( "/**", @@ -144,9 +155,54 @@ describe("parseAndTransformComments ends @example bodies at known tags", () => { ); }); + // The JSDoc forms of names left out of JSDOC_BLOCK_TAGS for their code forms. + it.each([ + ["@function"], + ["@function add"], + ["@mixin"], + ["@mixin Reveal"], + ['@import { Foo } from "./foo"'], + ['@import * as bar from "bar"'], + ])("ends an example at the JSDoc form %s", (tag) => { + const input = lines( + "/**", + " * @example", + " * foo()", + ` * ${tag}`, + " * and the rest", + " */", + ); + expect(run(input)).toBe( + lines( + "/**", + " * @example", + " * foo()", + ` * ${tag}`, + " * and the rest.", + " */", + ), + ); + }); + it("stores every tag name lowercased, as endsExample compares them", () => { for (const tag of JSDOC_BLOCK_TAGS) { expect(tag).toBe(tag.toLowerCase()); } }); + + /** + * A listed name must also read as a tag in prose, or the line that ends an + * example would be joined to the prose around it (CSS at-rules do not). + */ + it("reads every listed name as a tag in prose too", () => { + for (const tag of JSDOC_BLOCK_TAGS) { + const input = lines( + "/**", + " * Some prose that", + ` * @${tag} continues`, + " */", + ); + expect(run(input)).toContain(`\n * @${tag} continues\n`); + } + }); }); diff --git a/packages/comments/src/jsdoc-tags.ts b/packages/comments/src/jsdoc-tags.ts index 385b795..48170ab 100644 --- a/packages/comments/src/jsdoc-tags.ts +++ b/packages/comments/src/jsdoc-tags.ts @@ -1,14 +1,16 @@ /** * Block tag names from JSDoc, TSDoc, TypeScript, TypeDoc, Closure Compiler, the - * custom elements manifest and Doxygen, lowercased. Only one of these ends - * an @example body, so a decorator in the example's code whose name is not a - * tag ("@observable price = 0", "@computed get total()") stays code, while one - * named like a tag ("@readonly") still ends it. + * custom elements manifest and Doxygen, plus common pragmas, lowercased. Only a + * line that opens with one of these ends an @example body, so a decorator in + * the example's code whose name is not a tag ("@observable price = 0", + * "@computed get total()") stays code, while one named like a tag ("@readonly") + * still ends it. * * "import", "function" and "mixin" are left out on purpose: they are also CSS, - * Sass or TypeScript lines that an example's code is likely to hold. - * "property", "namespace" and "return" are CSS or Sass at-rules too, but stay - * in as tags that doc comments use far more often. + * Sass or TypeScript lines that an example's code is likely to hold; + * endsExample matches their JSDoc forms instead. "property", "namespace" and + * "return" are CSS or Sass at-rules too, but stay in as tags that doc comments + * use far more often. * */ export const JSDOC_BLOCK_TAGS = new Set([ @@ -140,6 +142,7 @@ export const JSDOC_BLOCK_TAGS = new Set([ "dict", "export", "externs", + "implicitcast", "final", "modifies", "nocollapse", @@ -147,6 +150,8 @@ export const JSDOC_BLOCK_TAGS = new Set([ "record", "struct", "suppress", + "noalias", + "nocompile", "unrestricted", // Custom elements manifest (web components, Lit). "attr", @@ -155,6 +160,7 @@ export const JSDOC_BLOCK_TAGS = new Set([ "cssprop", "cssproperty", "cssstate", + "customelement", "element", "slot", "tag", @@ -167,6 +173,13 @@ export const JSDOC_BLOCK_TAGS = new Set([ "pre", "retval", "tparam", + // Pragmas. + "jest-environment", + "jsx", + "jsxfrag", + "jsximportsource", + "jsxruntime", + "vitest-environment", // Common outside the standards. "examples", "note", diff --git a/packages/comments/src/lib.ts b/packages/comments/src/lib.ts index 40e6e1b..36dd998 100644 --- a/packages/comments/src/lib.ts +++ b/packages/comments/src/lib.ts @@ -321,11 +321,21 @@ function isExampleTag(line: string): boolean { * code, so an unknown one (`@observable price = 0`), 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 (`@property()`, - * `@di.injectable()`, `@click="save"`). + * `@di.injectable()`, `@click="save"`). The JSDoc forms of the names left out + * of the set for their CSS and Sass forms end it too: `@function` or `@mixin` + * alone or with one name, and TypeScript's `@import {` or `@import *`. */ function endsExample(line: string): boolean { const tag = /^\s?@([a-z][\w-]*)(?=[\s{:]|$)/.exec(line); - return tag !== null && JSDOC_BLOCK_TAGS.has(tag[1].toLowerCase()); + if (tag === null) { + return false; + } + const rest = line.trim(); + return ( + JSDOC_BLOCK_TAGS.has(tag[1].toLowerCase()) || + /^@(?:function|mixin)(?:\s+[\w$.]+)?$/.test(rest) || + /^@import\s+[{*]/.test(rest) + ); } function isVisuallyIndentedCode(line: string): boolean { From b9a6515a4ce6e707f7d0e55a36fc75f230a380e2 Mon Sep 17 00:00:00 2001 From: Arno V Date: Fri, 6 Nov 2026 15:24:05 -0500 Subject: [PATCH 4/6] fix(comments): end an @example at JSDoc namepaths and every TypeScript @import form - "@function" and "@mixin" with a JSDoc namepath ("Cart#add", "module:foo/bar~baz") end an example, as on main. A Sass kebab name with no namepath separator ("@mixin large-text") stays code. - "@import" ends an example in every TypeScript form: braces with or without a space, a star, or a default name followed by "," or "from". CSS and Sass "@import" (a string or url()) stay code. - Tests for both, plus a one-space-indented "@function add", a "$" and "." name, and a tag followed by "{" ("@type{string}"), which no test pinned. Co-Authored-By: Claude Opus 5.5 --- .../src/__tests__/lib.example-state.test.ts | 42 +++++++++++++++++++ .../src/__tests__/lib.example-tags.test.ts | 10 +++++ packages/comments/src/lib.ts | 10 +++-- 3 files changed, 59 insertions(+), 3 deletions(-) diff --git a/packages/comments/src/__tests__/lib.example-state.test.ts b/packages/comments/src/__tests__/lib.example-state.test.ts index 1d1879e..1051cb0 100644 --- a/packages/comments/src/__tests__/lib.example-state.test.ts +++ b/packages/comments/src/__tests__/lib.example-state.test.ts @@ -129,4 +129,46 @@ describe("parseAndTransformComments moves through @example states", () => { ); expect(run(once)).toBe(once); }); + + it("ends an example opened with one space at a JSDoc @function indented alike", () => { + const input = lines( + "/**", + " * @example", + " * foo()", + " * @function add", + " * and the rest", + " */", + ); + expect(run(input)).toBe( + lines( + "/**", + " * @example", + " * foo()", + " * @function add", + " * and the rest.", + " */", + ), + ); + }); + + it("ends an example at a tag followed by a brace", () => { + const input = lines( + "/**", + " * @example", + " * foo()", + " * @type{string} the value", + " * and the rest", + " */", + ); + expect(run(input)).toBe( + lines( + "/**", + " * @example", + " * foo()", + " * @type{string} the value", + " * and the rest.", + " */", + ), + ); + }); }); diff --git a/packages/comments/src/__tests__/lib.example-tags.test.ts b/packages/comments/src/__tests__/lib.example-tags.test.ts index 3a7cf7e..317e2e2 100644 --- a/packages/comments/src/__tests__/lib.example-tags.test.ts +++ b/packages/comments/src/__tests__/lib.example-tags.test.ts @@ -19,6 +19,8 @@ describe("parseAndTransformComments ends @example bodies at known tags", () => { // Left out of JSDOC_BLOCK_TAGS on purpose, so Sass stays code. ["@function rem($px) {"], ["@mixin center {"], + // A kebab-case name with no namepath separator is Sass, not JSDoc. + ["@mixin large-text"], ])("keeps %s inside the example as code", (code) => { const input = lines( "/**", @@ -161,8 +163,16 @@ describe("parseAndTransformComments ends @example bodies at known tags", () => { ["@function add"], ["@mixin"], ["@mixin Reveal"], + ["@function $.fn.x"], + // JSDoc namepaths. + ["@function Cart#add"], + ["@function module:cart~add"], + ["@mixin module:foo/bar"], ['@import { Foo } from "./foo"'], ['@import * as bar from "bar"'], + ['@import{ Bar } from "./foo"'], + ['@import Foo from "./foo"'], + ['@import Foo, { Bar } from "./foo"'], ])("ends an example at the JSDoc form %s", (tag) => { const input = lines( "/**", diff --git a/packages/comments/src/lib.ts b/packages/comments/src/lib.ts index 36dd998..143bd50 100644 --- a/packages/comments/src/lib.ts +++ b/packages/comments/src/lib.ts @@ -323,7 +323,9 @@ function isExampleTag(line: string): boolean { * anything but a space, "{", ":" or the end of the line (`@property()`, * `@di.injectable()`, `@click="save"`). The JSDoc forms of the names left out * of the set for their CSS and Sass forms end it too: `@function` or `@mixin` - * alone or with one name, and TypeScript's `@import {` or `@import *`. + * alone or with one name or JSDoc namepath (`Cart#add`, `module:foo/bar~baz`, + * but not a Sass kebab name such as `large-text`), and TypeScript's `@import` + * with braces, a star or a default name followed by "," or "from". */ function endsExample(line: string): boolean { const tag = /^\s?@([a-z][\w-]*)(?=[\s{:]|$)/.exec(line); @@ -333,8 +335,10 @@ function endsExample(line: string): boolean { const rest = line.trim(); return ( JSDOC_BLOCK_TAGS.has(tag[1].toLowerCase()) || - /^@(?:function|mixin)(?:\s+[\w$.]+)?$/.test(rest) || - /^@import\s+[{*]/.test(rest) + /^@(?:function|mixin)(?:\s+(?:[\w$.]+|[\w$./-]*[:~#][\w$.:~#/-]*))?$/.test( + rest, + ) || + /^@import\s*(?:[{*]|[A-Za-z_$][\w$]*\s*(?:,|\s+from\b))/.test(rest) ); } From 2e4319cc3754a28535bcf9302e08ad01c2374757 Mon Sep 17 00:00:00 2001 From: Arno V Date: Fri, 6 Nov 2026 15:29:21 -0500 Subject: [PATCH 5/6] fix(comments): keep the @import doc-form regex linear CodeQL flagged the @import rule in endsExample as a polynomial regular expression: "\s*" ran straight into "(?:,|\s+from)", so both quantifiers competed for the same run of spaces. On "@import$" plus 80,000 spaces it took 3.2 s. Each branch now owns its spaces ("(?:\s*,|\s+from\b)"), which takes 0.1 ms on the same input and accepts and rejects the same @import forms. Co-Authored-By: Claude Opus 5.5 --- packages/comments/src/lib.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/comments/src/lib.ts b/packages/comments/src/lib.ts index 143bd50..e9905b0 100644 --- a/packages/comments/src/lib.ts +++ b/packages/comments/src/lib.ts @@ -338,7 +338,8 @@ function endsExample(line: string): boolean { /^@(?:function|mixin)(?:\s+(?:[\w$.]+|[\w$./-]*[:~#][\w$.:~#/-]*))?$/.test( rest, ) || - /^@import\s*(?:[{*]|[A-Za-z_$][\w$]*\s*(?:,|\s+from\b))/.test(rest) + // Each branch owns its spaces, so no two quantifiers share a run of them. + /^@import\s*(?:[{*]|[A-Za-z_$][\w$]*(?:\s*,|\s+from\b))/.test(rest) ); } From 697fbd54cd7522c3abe1c63c99e4a67c8ceff653 Mon Sep 17 00:00:00 2001 From: Arno V Date: Fri, 6 Nov 2026 16:07:24 -0500 Subject: [PATCH 6/6] fix(comments): end an @example at kebab-case JSDoc @function and @mixin names The doc-form rule kept "@mixin large-text" as Sass code, but SCSS always has "(", "{" or quotes on the line and fails the end anchor anyway, so the guard only cost real JSDoc names: "@mixin my-mixin" and "@function do-thing" no longer ended an example, as they do on main. The name is now one class of JSDoc namepath characters, "-" included. - The doc-form tests move to lib.example-state.test.ts, with kebab and "@mixin center{" rows, and check that a second run changes nothing; both test files stay under 200 lines. - The endsExample comment says which Sass forms stay code. Co-Authored-By: Claude Opus 5.5 --- .../src/__tests__/lib.example-state.test.ts | 35 +++++++++++++--- .../src/__tests__/lib.example-tags.test.ts | 40 +------------------ packages/comments/src/lib.ts | 12 +++--- 3 files changed, 37 insertions(+), 50 deletions(-) diff --git a/packages/comments/src/__tests__/lib.example-state.test.ts b/packages/comments/src/__tests__/lib.example-state.test.ts index 1051cb0..b7c0a49 100644 --- a/packages/comments/src/__tests__/lib.example-state.test.ts +++ b/packages/comments/src/__tests__/lib.example-state.test.ts @@ -139,7 +139,8 @@ describe("parseAndTransformComments moves through @example states", () => { " * and the rest", " */", ); - expect(run(input)).toBe( + const once = run(input); + expect(once).toBe( lines( "/**", " * @example", @@ -149,26 +150,50 @@ describe("parseAndTransformComments moves through @example states", () => { " */", ), ); + expect(run(once)).toBe(once); }); - it("ends an example at a tag followed by a brace", () => { + /** + * A tag followed by "{", then the JSDoc forms of the names left out of + * JSDOC_BLOCK_TAGS for their Sass and CSS forms. + */ + it.each([ + ["@type{string} the value"], + ["@function"], + ["@function add"], + ["@function do-thing"], + ["@mixin"], + ["@mixin Reveal"], + ["@mixin my-mixin"], + ["@function $.fn.x"], + ["@function Cart#add"], + ["@function module:cart~add"], + ["@mixin module:foo/bar"], + ['@import { Foo } from "./foo"'], + ['@import * as bar from "bar"'], + ['@import{ Bar } from "./foo"'], + ['@import Foo from "./foo"'], + ['@import Foo, { Bar } from "./foo"'], + ])("ends an example at %s", (tag) => { const input = lines( "/**", " * @example", " * foo()", - " * @type{string} the value", + ` * ${tag}`, " * and the rest", " */", ); - expect(run(input)).toBe( + const once = run(input); + expect(once).toBe( lines( "/**", " * @example", " * foo()", - " * @type{string} the value", + ` * ${tag}`, " * and the rest.", " */", ), ); + expect(run(once)).toBe(once); }); }); diff --git a/packages/comments/src/__tests__/lib.example-tags.test.ts b/packages/comments/src/__tests__/lib.example-tags.test.ts index 317e2e2..d290a6b 100644 --- a/packages/comments/src/__tests__/lib.example-tags.test.ts +++ b/packages/comments/src/__tests__/lib.example-tags.test.ts @@ -19,8 +19,7 @@ describe("parseAndTransformComments ends @example bodies at known tags", () => { // Left out of JSDOC_BLOCK_TAGS on purpose, so Sass stays code. ["@function rem($px) {"], ["@mixin center {"], - // A kebab-case name with no namepath separator is Sass, not JSDoc. - ["@mixin large-text"], + ["@mixin center{"], ])("keeps %s inside the example as code", (code) => { const input = lines( "/**", @@ -157,43 +156,6 @@ describe("parseAndTransformComments ends @example bodies at known tags", () => { ); }); - // The JSDoc forms of names left out of JSDOC_BLOCK_TAGS for their code forms. - it.each([ - ["@function"], - ["@function add"], - ["@mixin"], - ["@mixin Reveal"], - ["@function $.fn.x"], - // JSDoc namepaths. - ["@function Cart#add"], - ["@function module:cart~add"], - ["@mixin module:foo/bar"], - ['@import { Foo } from "./foo"'], - ['@import * as bar from "bar"'], - ['@import{ Bar } from "./foo"'], - ['@import Foo from "./foo"'], - ['@import Foo, { Bar } from "./foo"'], - ])("ends an example at the JSDoc form %s", (tag) => { - const input = lines( - "/**", - " * @example", - " * foo()", - ` * ${tag}`, - " * and the rest", - " */", - ); - expect(run(input)).toBe( - lines( - "/**", - " * @example", - " * foo()", - ` * ${tag}`, - " * and the rest.", - " */", - ), - ); - }); - it("stores every tag name lowercased, as endsExample compares them", () => { for (const tag of JSDOC_BLOCK_TAGS) { expect(tag).toBe(tag.toLowerCase()); diff --git a/packages/comments/src/lib.ts b/packages/comments/src/lib.ts index e9905b0..4b17a01 100644 --- a/packages/comments/src/lib.ts +++ b/packages/comments/src/lib.ts @@ -323,9 +323,11 @@ function isExampleTag(line: string): boolean { * anything but a space, "{", ":" or the end of the line (`@property()`, * `@di.injectable()`, `@click="save"`). The JSDoc forms of the names left out * of the set for their CSS and Sass forms end it too: `@function` or `@mixin` - * alone or with one name or JSDoc namepath (`Cart#add`, `module:foo/bar~baz`, - * but not a Sass kebab name such as `large-text`), and TypeScript's `@import` - * with braces, a star or a default name followed by "," or "from". + * alone or with one name or JSDoc namepath (`do-thing`, `Cart#add`, + * `module:foo/bar~baz`), and TypeScript's `@import` with braces, a star or a + * default name followed by "," or "from". SCSS keeps its "(", "{" or quotes on + * the line, so it stays code; a bare indented-syntax `@mixin theme` ends the + * example, as it always has. */ function endsExample(line: string): boolean { const tag = /^\s?@([a-z][\w-]*)(?=[\s{:]|$)/.exec(line); @@ -335,9 +337,7 @@ function endsExample(line: string): boolean { const rest = line.trim(); return ( JSDOC_BLOCK_TAGS.has(tag[1].toLowerCase()) || - /^@(?:function|mixin)(?:\s+(?:[\w$.]+|[\w$./-]*[:~#][\w$.:~#/-]*))?$/.test( - rest, - ) || + /^@(?:function|mixin)(?:\s+[\w$.:~#/-]+)?$/.test(rest) || // Each branch owns its spaces, so no two quantifiers share a run of them. /^@import\s*(?:[{*]|[A-Za-z_$][\w$]*(?:\s*,|\s+from\b))/.test(rest) );