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

[biw]

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]

Does the compiler preserve these comments in the emitted .d.ts files? I recall sometimes comments in certain places get discarded.

TSDoc itself doesn't (yet) dictate very specifically where comments can appear. That is determined by the documentation tool that uses the TSDoc library. Which tool are you using?

[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

[littlecold233]

Any progress on this issue?

[octogonz]

To answer my earlier question, the TypeScript compiler does preserve these comments in the .d.ts file:

export declare 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';

So I think this feature seems pretty reasonable. 👍

But as mentioned previously, the TSDoc standard can specify that "yes this is an appropriate place to put a comment", but the TSDoc library only parses comments. It does not parse API signatures. That part is handled by your documentation tool such as API Extractor or TypeDoc.

So you'd need to open an issue to request this feature for the documentation tool.

[Gerrit0]

If this is specified as valid, what would documented types look like? Right now both api-extractor and typedoc just display the type. Do we need special casing for unions? Are doc comments allowed on union types within another type? Would this result in users expecting to be able to include comments almost anywhere within a type and have them be picked up?

type Messy = [ /** a */ 1, /** b */ 2 | /** c */ 3]

[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

[TheMrZZ]

It looks like this feature was accepted, when looking at the Version 1.0 tracking. According to Gerrit0's comment, it should be available by the end of the year if I understood correctly!

Edit: I misunderstood - see the comment below.

[Gerrit0]

Note: TypeDoc != TSDoc. This hasn't been added to the TSDoc standard yet, but TypeDoc plans to support it. Other documentation generators might not necessarily support it.