Support parsing TSDoc string comments

[christianalfoni]

Hi there!

I had a issue trip around Github and finally ended up here :)

Last issue was: microsoft/vscode#95408

I am using String Literal types to define classnames and would love to populate with some more information.

So basically:

type TClassnames = 
   /** Some docs about red-500 */
    | 'bg-color-red-500'
   /** Some docs about red-600 */
    | 'bg-color-red-600'

I would expect it to populate the docs on the right side of the intellisense:

This is how we can document with properties:

Which would be amazing to have on string literals.

I thought it was a TSDoc issue, but given this context: microsoft/tsdoc#164, it seems to be VSCode not parsing it... though then it seems to actually be Typescript related?

[TheMrZZ]

This is an underrated feature. Nowadays, a lot of enum are done using string literals - a powerful feature that puts Typescript above a lot of static languages. However, those enumerations lack proper documentation, which causes several problems.

Here is the link of the related issue in the tsdoc repository.

Here are a few real-world use-cases I thought of:

React Native CSS

<Text style={{
  color: 'blue',
  alignSelf: 'center',
}}> This is a blue text </Text>

Adding string comments would simplify the understanding of each possibility (each color, each possible alignments).

This is applicable to all properties with a defined set of string values.

Configuration files

For example, let's take a tsconfig.json file:

{
  "module": "commonjs"
}

Currently, the documentation looks like this:

While we know all the possible options, there is no way to understand what they actually do. String comments could tell explicitly the user what each option is supposed to change.

This is applicable to all configuration files that are made with TS, not only tsconfig.json.

Material-UI

Material-UI relies a lot on string enumerations, but they are not always easy to understand.

<Button variant="contained"> My Button </Button>

In the above example, while variant is trivial to understand, it's not easy to guess what the "contained" value means. You have to rely on the external documentation, where that shouldn't be necessary.

This is applicable to all React props with a defined set of string values.

In conclusion, I think it's a very good idea, and it could simplify documentation in a lot of projects.

[NemoStein]

As I mentioned in multiple other issues, I really don't care for TS as all my development is in JS.
I just want to have proper documentation in situations like this:

It just happens that VSCode (and other tools) uses TSC behind the hood.

[phaux]

It would be nice if at least this was working (it doesn't):

/** Foo docs. */
type Foo = "foo"

/** Bar docs. */
type Bar = "bar"

type Test = Foo | Bar

const x: Test = "foo" // No docs for `foo` when typing.

[DanielSWolf]

We often use string literal types as a lightweight alternative to full enums. It's really frustrating that we can't document the individual options in a way that VS Code recognizes. In the following code, all the doc-strings on the options are simply lost:

/** Controls the alignment of text when printed. */
type TextAlignment =
    /** Left-aligns the text. */
    | "left"
    /** Right-aligns the text. */
    | "right"
    /** Centers the text horizontally. */
    | "center";

There are identical issues in the TypeDoc repo (TypeStrong/typedoc#1710) and the TSDoc repo (microsoft/tsdoc#164), but they all require proper support from TypeScript first.

[vivianmauer]

Any update on this? 😕

[laizp]

Any progress? It would be an amazing feature. 😕

[cseas]

We also have this requirement for adding TSDoc for our design system tokens.
razorpay/blade#1249

Similar ask on StackOverflow:
https://stackoverflow.com/questions/63067208/writing-more-descriptive-intellisense-docs-for-typescript-union-types

For now, we're working around this limitation by providing the feature in a VSCode extension:
https://marketplace.visualstudio.com/items?itemName=cseas.razorpay-blade-intellisense

[starball5]

And a recent duplicate of the above linked Stack Overflow question: How can I get hover documentation for string literals matching documented union type members in JS/TS?

[hylickipiotr]

Any updates?