Support parsing TSDoc string comments

christianalfoni commented 4 years ago

Hi there!

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

Last issue was: https://github.com/microsoft/vscode/issues/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:

Screenshot 2020-02-12 at 10 10 59

Which would be amazing to have on string literals.

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

TheMrZZ commented 4 years ago

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: Capture d’écran de 2020-09-16 13-19-44

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 commented 4 years ago

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 commented 4 years ago

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 commented 2 years ago

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.