Support for comments inside JSDoc @example comments

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

No se nombran archivos fuente ni pruebas. Empieza rastreando cómo TypeScript gestiona los bloques @example de JSDoc y los delimitadores de comentarios anidados, y luego compara la entrada mostrada con la representación deseada de la documentación. Se considera terminado cuando los comentarios dentro de un bloque @example se conservan sin cambiar el comportamiento existente de JSDoc.