Support adding JSDoc comments for union constituents

[cseas]

Suggestion

🔍 Search Terms

• typescript jsdoc for union constituents
• jsdoc comments for typescript variable values autocomplete in vscode intellisense
• chakra ui mui vscode intellisense for token values

✅ 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

Support adding JSDoc comments for individual union constituents.

📃 Motivating Example

JSDoc comments for union members would appear in IDE IntelliSense (refer below example).

💻 Use Cases

Consider the following type for spacing tokens in a UI library.

type Spacing =
  /** 4px */
  | 'spacing.1'
  /** 8px */
  | 'spacing.2';

We want the equivalent px values of these tokens to be visible in the IDE wherever this type is used in our components for spacing based props. This way our users wouldn't need to refer the library documentation for what the final value of a token is.

Currently this is only possible by building an extension for the IDE, something similar to Tailwind CSS IntelliSense.

We're discussing workarounds here: razorpay/blade#1249

Similar use-case has also been asked on StackOverflow:
https://stackoverflow.com/questions/63067208/writing-more-descriptive-intellisense-docs-for-typescript-union-types

[cseas]

Update:

I found this comment in a TSDoc issue that explains the use-case well:
microsoft/tsdoc#164 (comment)

I see the author has already opened an issue for this but it didn't appear in any of my Google searches (check in Issue description)

• Support parsing TSDoc string comments  #38106

Closing as #38106 captures the requirement well.