Repository navigation
fix(comments): end an @example only at a known JSDoc tag - #747
Merged
Merged
Conversation
- 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>
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #745.
What changed
Since #744,
comments --merge-line-commentskeeps the body of an@exampleline 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 = 0or@computed get total()ended the example, and the code after it was reflowed as prose.jsdoc-tags.ts: JSDoc, TSDoc, TypeScript, TypeDoc, Closure Compiler, the custom elements manifest, Doxygen and common pragmas. They are compared case-insensitively, so@typeParamand@categoryDescriptionstill end one.(,.or=(@property()) is code.function,mixinandimportare 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:@functionor@mixin, alone or with one name or a JSDoc namepath (Cart#add,module:foo/bar~baz);@importform (braces,*, or a default name followed by,orfrom).main. Every line that ends an example on this branch also ends one onmain; 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 andmaindoes not.Not in this PR: the other half of #745, a
// @example Basic usagetitle after a//summary with no period. A capitalized word after@examplecan'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 onmain. The JSDoc form (/** … @example Basic usage) already works.Verification
lib.example-tags.test.ts(every added tag name, the Sass, CSS and JSDoc forms, the wrapped-sentence case) andlib.example-state.test.ts(a second@example, decorators, capitalized and indented tags, in both comment forms).{/:check, the indent bound, the namepath and import forms, or the Sass kebab guard turns at least one test red.@example,@observableand titled examples.mainvs this branch on the 204 files that contain@exampleacross ui-components, node-cli, sassysaint, clubroad, episodia and auth0-thin: no file changes, and none changes on a second pass./gstack-reviewran 3 fix cycles. Its last pass found only the namepath and@importgaps fixed in the final commit, so it ended at its cycle limit without a clean sign-off.🤖 Generated with Claude Code