Skip to content

fix(comments): end an @example only at a known JSDoc tag - #747

Merged
aversini merged 6 commits into
mainfrom
claude/issue-745-known-tags
Nov 6, 2026
Merged

aversini merged 6 commits into
mainfrom
claude/issue-745-known-tags

Conversation

@aversini

@aversini aversini commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #745.

What changed

Since #744, comments --merge-line-comments keeps the body of an @example line for line until the next tag. To tell a real tag from a decorator in the example's code, it checked only the character after the name. So a lowercase decorator such as @observable price = 0 or @computed get total() ended the example, and the code after it was reflowed as prose.

  • An example now ends only at a known block tag. The names live in the new jsdoc-tags.ts: JSDoc, TSDoc, TypeScript, TypeDoc, Closure Compiler, the custom elements manifest, Doxygen and common pragmas. They are compared case-insensitively, so @typeParam and @categoryDescription still end one.
  • The existing rules still apply. A capitalized decorator, a tag indented by two or more spaces, or a tag name followed by (, . or = (@property()) is code.
  • function, mixin and import are left out of the list, because inside example code they are usually Sass or CSS (@function rem($px) {, @mixin center {, @import "theme.css";). Their JSDoc forms still end an example:
    • @function or @mixin, alone or with one name or a JSDoc namepath (Cart#add, module:foo/bar~baz);
    • every TypeScript @import form (braces, *, or a default name followed by , or from).
  • Never ends more examples than main. Every line that ends an example on this branch also ends one on main; only unknown names stop ending one. Two fuzz runs compared the two rules on 1.5 million and 32,000 generated lines and found none where this branch ends an example and main does not.

Not in this PR: the other half of #745, a // @example Basic usage title after a // summary with no period. A capitalized word after @example can't be told apart from a sentence that wraps there ("…the body of an / @example JSDoc tag…"). An earlier commit tried and split such sentences with a stray period, so titled // examples behave as they do on main. The JSDoc form (/** … @example Basic usage) already works.

Verification

  • 235 tests pass in the package. The new tests are in lib.example-tags.test.ts (every added tag name, the Sass, CSS and JSDoc forms, the wrapped-sentence case) and lib.example-state.test.ts (a second @example, decorators, capitalized and indented tags, in both comment forms).
  • Each rule was mutated on its own: changing the tag list, the lowercase comparison, the {/: check, the indent bound, the namepath and import forms, or the Sass kebab guard turns at least one test red.
  • A fuzz run of 40k random blocks found no reordered text and no change on a second pass. The property tests now generate @example, @observable and titled examples.
  • main vs this branch on the 204 files that contain @example across ui-components, node-cli, sassysaint, clubroad, episodia and auth0-thin: no file changes, and none changes on a second pass.
  • /gstack-review ran 3 fix cycles. Its last pass found only the namepath and @import gaps fixed in the final commit, so it ended at its cycle limit without a clean sign-off.

🤖 Generated with Claude Code

aversini and others added 4 commits November 6, 2026 13:12
- 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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
…@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 <noreply@anthropic.com>
Comment thread packages/comments/src/lib.ts Fixed
aversini and others added 2 commits November 6, 2026 15:29
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 <noreply@anthropic.com>
… 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 <noreply@anthropic.com>
@aversini
aversini merged commit d1c3558 into main Nov 6, 2026
4 checks passed
@aversini
aversini deleted the claude/issue-745-known-tags branch November 6, 2026 21:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

comments: end an @example body only at known JSDoc tag names

2 participants