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..b7c0a49 --- /dev/null +++ b/packages/comments/src/__tests__/lib.example-state.test.ts @@ -0,0 +1,199 @@ +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", + // 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();", + "// 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); + }); + + it("ends an example opened with one space at a JSDoc @function indented alike", () => { + const input = lines( + "/**", + " * @example", + " * foo()", + " * @function add", + " * and the rest", + " */", + ); + const once = run(input); + expect(once).toBe( + lines( + "/**", + " * @example", + " * foo()", + " * @function add", + " * and the rest.", + " */", + ), + ); + expect(run(once)).toBe(once); + }); + + /** + * 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()", + ` * ${tag}`, + " * and the rest", + " */", + ); + const once = run(input); + expect(once).toBe( + lines( + "/**", + " * @example", + " * foo()", + ` * ${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 new file mode 100644 index 0000000..d290a6b --- /dev/null +++ b/packages/comments/src/__tests__/lib.example-tags.test.ts @@ -0,0 +1,180 @@ +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 (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";'], + ['@import url("print.css") print;'], + // Left out of JSDOC_BLOCK_TAGS on purpose, so Sass stays code. + ["@function rem($px) {"], + ["@mixin center {"], + ["@mixin center{"], + ])("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("keeps a // sentence that wraps at a capitalized word after @example in one piece", () => { + const input = lines( + "foo();", + "// The reflow keeps the body of an", + "// @example JSDoc tag line for line, and joins the prose after it", + "bar();", + ); + const once = run(input); + expect(once).toBe( + lines( + "foo();", + "/**", + " * The reflow keeps the body of an @example JSDoc tag line for line, and joins", + " * the prose after it.", + " */", + "bar();", + ), + ); + 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", + "implicitCast", + "noalias", + "nocompile", + "customElement", + "jest-environment", + "jsx", + "jsxFrag", + "jsxImportSource", + "jsxRuntime", + "vitest-environment", + ])("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()); + } + }); + + /** + * 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/__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/__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..48170ab --- /dev/null +++ b/packages/comments/src/jsdoc-tags.ts @@ -0,0 +1,190 @@ +/** + * Block tag names from JSDoc, TSDoc, TypeScript, TypeDoc, Closure Compiler, the + * 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; + * 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([ + // 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", + "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", + "implicitcast", + "final", + "modifies", + "nocollapse", + "nosideeffects", + "record", + "struct", + "suppress", + "noalias", + "nocompile", + "unrestricted", + // Custom elements manifest (web components, Lit). + "attr", + "attribute", + "csspart", + "cssprop", + "cssproperty", + "cssstate", + "customelement", + "element", + "slot", + "tag", + "tagname", + // Doxygen. + "brief", + "bug", + "details", + "post", + "pre", + "retval", + "tparam", + // Pragmas. + "jest-environment", + "jsx", + "jsxfrag", + "jsximportsource", + "jsxruntime", + "vitest-environment", + // 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 4516e1b..4b17a01 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,32 @@ 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 - * (`@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 known block + * 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"`). 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 (`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 { - return /^\s?@[a-z][\w-]*(?=[\s{:]|$)/.test(line) && isTagLine(line); + const tag = /^\s?@([a-z][\w-]*)(?=[\s{:]|$)/.exec(line); + if (tag === null) { + return false; + } + const rest = line.trim(); + return ( + JSDOC_BLOCK_TAGS.has(tag[1].toLowerCase()) || + /^@(?: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) + ); } function isVisuallyIndentedCode(line: string): boolean { @@ -791,7 +809,8 @@ function mergedJsDocLines(texts: string[]): string[] { kind !== "prose" || note || // An @example alone or with a caption never continues a sentence, even - // one without a period. + // 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) ||