Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/comments/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
199 changes: 199 additions & 0 deletions packages/comments/src/__tests__/lib.example-state.test.ts
Original file line number Diff line number Diff line change
@@ -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);
});
});
180 changes: 180 additions & 0 deletions packages/comments/src/__tests__/lib.example-tags.test.ts
Original file line number Diff line number Diff line change
@@ -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`);
}
});
});
3 changes: 3 additions & 0 deletions packages/comments/src/__tests__/lib.property.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@ const token = fc.oneof(
"note:",
"aNOTE:",
"@param",
"@returns",
"@example",
"@observable",
"@auth0/auth0-react",
"@media",
"-",
Expand Down
Loading
Loading