RFC: Specify that doc comments are allowed on simple union types

Hello,

I can’t find any documentation on adding tsdocs to a typescript string literal type. I was wondering if the following is possible:

type InputType = 
/** the TSDoc doesn't work for num1, but I'd like it to */
| 'num1'
/** the TSDoc doesn't work for num2, but I'd also like it to */
| 'num2'

export const test = (...input: InputType[]) => {
    return input
}

// I'd like to get the TSDoc from 'num1' string literal to show up
// when inputting it into the `tac` function but it does not currently show
test('num1')

I’m not 100% tied to using string literal types, so if there is another way to do this with enums, etc., I’d love to learn 😄

If the above is not currently possible, I’d love to work to add it to tsdoc (with some guidance 😄).

Thanks!

[octogonz]

@Gerrit0 my thinking to restrict this feature to a very special pattern that is commonly used like an enum. We could give it a name like “union enum”.

For example, these would be union enums:

/**
 * A standard system color.
 */
export type Color = 
  /**
   * The color `#ff0000`
   */
  'red' | // do we care whether "|" is before/after the comment? Not really
  /**
   * The color `#00ff00`
   */
  'green' 
  /**
   * The color `#0000ff`
   */
  | 'blue';

/**
 * A binary digit.
 */
export type Bit = /** zero */  0  |  /** one*/ 1;

But it’s optional. For example, maybe a documentation tool only treats a type as an “union enum” if at least one of the members has a /** */ comment.

And it would NOT apply to any other generalized expressions, not even this sort of thing:

// NOT a union enum:
type Mammal = Cat | Dog | Horse;

For the most part, such a feature would be a feature request for your particular documentation tool. If TSDoc “supports” this feature, its role is merely to:

• specify that it’s “standard” to put doc comments on these subexpressions
• provide a declaration reference notation for referring to them

[christianalfoni]

Hi there, I have the same thing. I am using String Literal types to define classnames and would love to populate with some more information.

So basically:

type TClassnames = 
	| 'bg-color-red-500'
    | 'bg-color-red-600'

I would love 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