You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
comments: end an @example body only at known JSDoc tag names #745
--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:
A lowercase decorator followed by a space ends the example. The code after it is then reflowed as prose.
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().
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.
Activity