Support documentation for string literal types in unions

[socsieng]

• I have checked issues with enhancement label and found no duplicates

Problem

Normally I would use an enum for this, however, I am documenting an existing JavaScript library as a .d.ts file where the actual type doesn't exist in JavaScript.

There doesn't appear to be any support for documenting or applying an @tag to individual string literals in a type union.

Example:

type CallbackType = /** Fired when ready */ 'ready' |
  /** Fired when complete */ 'complete' |
  /** Fired when an error occurs */ 'error' |
  /** @hidden */ 'unknown';

The above example has no effect on the generated documentation.

Suggested Solution

Add support for documenting individual items in a union type including @tags.

[Gerrit0]

This gets complicated quickly. Right now we don't support documenting any parts of types except for properties of interfaces. If we add support for members of a union, it seems reasonable to also make it possible to document parts of an intersection, properties within those parts... etc. I'm also not really sure how this extra documentation would be rendered.

An alternative method of documenting this could be:

interface Callbacks {
  /** Fired when ready */
  ready: never;
  /** Fired when complete */
  complete: never;
  /** Fired when an error occurs */
  error: never;
  /** @hidden */
  unknown: never
}

type CallbackType = keyof Callbacks

[socsieng]

Thanks @Gerrit0.

I ended up going with a slight variation on this:

type Callbacks = {
  /** Fired when ready */
  ready: never;
  /** Fired when complete */
  complete: never;
  /** Fired when an error occurs */
  error: never;
  /** @hidden */
  unknown: never
}

type CallbackType = keyof Callbacks

I preferred the output of the documentation following a type declaration instead of an interface one.

In either case, these are the results that I've observed:

• VSCode: Displays CallbackType values as union of strings (expected)
• VSCode: Doesn't honor the @hidden tag (unexpected)
• TypeDoc: Honors the @hidden tag (expected)
• TypeDoc: Doesn't automatically link to the Callbacks type (unexpected)

Further to the last point, the output of the CallbackType documentation reads as follows:

T CallbackType: keyof Callbacks

But I expected Callbacks to be hyperlinked like this:

T CallbackType: keyof [[Callbacks]]

It's not 100%, but it is better than nothing.

[Gerrit0]

The @hidden annotation is TypeDoc specific. If you want to remove something from a declaration file after build so that it doesn't show up in VSCode you'll need @internal (which TypeDoc supports, if you pass --stripInternal)

Not linking to callbacks in keyof Callbacks sounds like a bug to me.

[Gerrit0]

You might be interested in microsoft/tsdoc#164, if a solution is discovered there I'd like to revisit this.

[socsieng]

Cool. Thanks for the share.