Support for enum-like use of string literal types

[DanielSWolf]

Search Terms

enum, string literal type, union type

Problem

Instead of using full enums, TypeScript APIs often use string literal types to achieve a more lightweight API. The following example is straight from the TypeScript documentation:

function printText(s: string, alignment: "left" | "right" | "center") {
  // ...
}

If I wanted to document this function, this is what I'd write:

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

function printText(s: string, alignment: TextAlignment) {
  // ...
}

However, TypeDoc seems to ignore the doc comments above the individual options. Here is the output with TypeDoc 0.22.4:

Suggested Solution

I'd like TypeDoc to decorate the individual string options with the corresponding doc comments.

[Gerrit0]

I looked into doing this, and it is surprisingly annoying to do... the leading trivia on each member of that union is just " ", because leading trivia from before the | is not included. It's possible, just rather annoying...

[DanielSWolf]

I thought maybe it was just the placement of the pipe characters (at the start of each line, rather than at the end). But it seems to me that the TypeScript parser (which I assume you're using) doesn't expect any comments at all before union type alternatives. I just tried out several variations in the AST explorer, but both leading and trailing comments are always undefined.

Would it make sense to create an upstream issue for TypeScript?

[Gerrit0]

We can do it without upstream support, it's just slightly annoying, it sounds like this is something the TypeScript team is willing to improve support for though, I asked about this in the compiler-api channel in the TS Discord, and got this response:

Nathan Shively-Sanders 09/24/2021
You can ask for the leading trivia of any node, but this includes whitespace and isn't necessarily parsed as jsdoc.
It could also make sense to attach jsdoc to individual union members, the parser just doesn't do it right now.
<help wanted> on both those ideas, I guess -- file a bug to let us know if you want to make it happen

[DanielSWolf]

At the risk of going slightly off-topic: The documentation comments we write aren't just used with TypeDoc. Developers also rely on tooltips in VS code when using our code. So we try to avoid features that aren't supported by both systems.

For instance, we quickly stopped using the (otherwise immensely useful) @inheritdoc SomeOtherSymbol syntax: The results were great in TypeDoc, but unusable in VS Code.

Returning to this topic: At the moment, we comment the options of a union type within the main comment block of the union type itself. It would be great if there was a way to document these options individually. However, if that way was limited to TypeDoc, using it would actively worsen the development experience in VS code, where this information would simply be missing. This is why I'd prefer a concerted approach (knowing, of course, that this means extra effort for whomever does the coordination).

[Gerrit0]

I completely agree! Good looking documentation in editors is really important, but I don't really have enough time to coordinate efforts across TypeDoc / VSCode / TypeScript. This change would affect all three.

The lack of good editor tooling for string literal enums is the main reason TypeDoc supports the @enum tag on as const literals (docs)

[Gerrit0]

I don't think it makes sense for TypeDoc to do this before microsoft/TypeScript#38106, I don't want to encourage patterns in documentation which result in a poor experience in editors. Once the TypeScript issue has been resolved, definitely open to implementing support here.