Support for comments inside JSDoc @example comments

[ackvf]

Suggestion

🔍 Search Terms:

comments inside jsdoc, jsdoc inception

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

I am writing a custom helper type that allows me to provide JSDoc comments for properties of any other object or interface that is inaccessible for changes.
I need to document the feature and usage, but I can't close a comment section inside JSDoc comment's.

Code:

/**
 * This type allows to add JSDoc annotation to any type without causing conflicts.
 *
 * @example
 * type IconButtonProps =
 *  & JSDoc
 *  & ShorthandVariantsAndSizes
 *
 * type JSDoc = Documentation<ShorthandVariantsAndSizes, {
 *  /**
 *   * **variant**: Color theme for the button.
 *   * - `light` variant is white on all themes.
 *   \*\/
 *   variant?: unknown  // <- note: this `?: unknown` optional type is important
 * }>
 */
type Documentation<T, TargetType extends { [K in keyof T]?: unknown }> = TargetType

JSDoc invoked:

💻 Use Cases

Desired:

Result:

📃 Motivating Example

const sizeKeys = ['small', 'large'] as const

// this is a mapped type and therefore doesn't allow to add JSDoc comments
type ExplodedSizes = { [key in typeof sizeKeys]?: unknown }

type JSDoc = Documentation<ExplodedSizes, {
  /**
   * **size**: Button size.
   * - `64px`
   */
  large?: unknown
  /**
   * **size**: Button size.
   * - `32px`
   */
  small?: unknown
}>

// this merges the jsdoc annotation with correct types
export type IconButtonProps =
  & JSDoc
  & ExplodedSizes

export const IconButton: React.FC<IconButtonProps> = (props) => <> </> 

// later when using the component
const render = <IconButton /> // <- gets correct intellisense with JSDoc comments here

[DanielRosenwasser]

#47679 is related. #50677 has a tenative fix, but we haven't discussed it much recently. I don't recall if it supports \ escaping.

[ackvf]

@DanielRosenwasser I don't think it does or ever did, but it was the most intuitive solution for the reader when I accept that it doesn't work. Using non-functioning escaping still conveys the message to the next developer who reads the documentation, so it was the best solution.

I tried various different combinations with spaces, multiple * or multiple /, etc.

[ackvf]

Heads up, I found a neat workaround that is not ideal due to syntax highlight, but it does produce a little clearer output.

Solution lies in replacing * with ★ or ⋆, see also https://www.symbolcopy.com/star-symbol.html

/**
 * This type allows to add JSDoc annotation to any type without causing conflicts.
 *
 * @example
 * type IconButtonProps =
 *  & JSDoc
 *  & ShorthandVariantsAndSizes
 *
 * type JSDoc = Documentation<ShorthandVariantsAndSizes, {
 *  /★★
 *   * **variant**: Color theme for the button.
 *   * - `light` variant is white on all themes.
 *   ★/
 *   variant?: unknown  // <- note: this `?: unknown` optional type is important
 *   // ... other props
 * }>
 */
type Documentation<T, TargetType extends { [K in keyof T]?: unknown }> = TargetType

The result is that the "comment" now looks weird with that syntax highlight, but the important bit, "variant?: unknown" doesn't look as a comment as in original screenshot and looks as a property.

---

So, if I were to choose between those two, I would pick the latter.

[jaydenseric]

See prior discussion microsoft/tsdoc#166 (comment) .