Repository: TypeScript
Issue: Support for comments inside JSDoc @example comments
Labels: Suggestion,In Discussion,Domain: JSDoc

# Suggestion

## 🔍 Search Terms: 

comments inside jsdoc, jsdoc inception

## ✅ Viability Checklist

<!--
   Suggestions that don't meet all these criteria are very, very unlikely to be accepted.
   We always recommend reviewing the TypeScript design goals before investing time writing
   a proposal for ideas outside the scope of the project.
-->
My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-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:**

![image](https://user-images.githubusercontent.com/2313018/214411789-64a12976-d61e-4337-8629-3b3abf811058.png)

```ts
/**
 * 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:**

![image](https://user-images.githubusercontent.com/2313018/214412286-95837b5c-28e8-4367-9e5c-61218b097cc5.png)


## 💻 Use Cases

**Desired:**

![image](https://user-images.githubusercontent.com/2313018/214405894-0d6cf513-1b90-494f-847c-6e24a28d1549.png)

**Result:**

![image](https://user-images.githubusercontent.com/2313018/214406406-0f894b6f-ab95-4161-8331-3df015da162e.png)


## 📃 Motivating Example

```ts
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
```

![image](https://user-images.githubusercontent.com/2313018/214416742-3b26c893-f596-4241-ad70-5f2dbffeea18.png)