Skip to content

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

Closed

Description

@aversini

Follow-up to #735 / #744.

Problem

--merge-line-comments keeps the body of an @example tag line for line until the next tag. To tell a real tag from a decorator inside the example, endsExample looks at the character after the name: a lowercase tag followed by a space, {, : or the end of the line ends the example. Each review round of #744 had to adjust that set, and it still misfires on two shapes that main gets wrong as well:

  1. A lowercase decorator followed by a space ends the example. The code after it is then reflowed as prose.

    /**
     * @example
     * @observable price = 0
     * const cart = new Cart()
     */

    This comes out as const cart = new Cart()., and longer code after it gets joined. The same happens with MobX @computed get total() and @action handle().

  2. A TSDoc example title is joined to a summary with no period.

    // Usage
    // @example Basic usage
    // const a = 1
    // const b = 2

    This becomes Usage @example Basic usage const a = 1 const b = 2.. A bare @example and @example <caption>…</caption> are protected, but a plain-text title is not, because it can't be told apart from a prose line such as @example tag using ….

Proposal

End an example only at a known JSDoc/TSDoc block tag name (param, returns, throws, see, since, deprecated, default, remarks, typeParam, example, …). Check it against a set, the way CSS_AT_RULES already works in isTagLine. Real tags would then close an example whatever follows them, and @observable, @click and other decorators never would.

Fixing (2) needs its own rule. One option is to treat @example <Capitalized title> at the start of a // line as an opener.

🤖 Generated with Claude Code

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions