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:

[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.

⭐ 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.

Screenshot 2023-06-02 at 8 37 56 AM

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

We're discussing workarounds here: https://github.com/razorpay/blade/issues/1249

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

microsoft / TypeScript

Support adding JSDoc comments for union constituents #54510