Ways for pure JavaScript consumers to obtain type information from TypeScript libraries about tsdoc

[aciccarello]

Related: microsoft/TypeScript#10

[octogonz]

We chatted about this. @liamross clarified that for now he's mainly interested in generating web site documentation. I suggested to take at API Extractor or TypeDoc, both of which are complete documentation tools (whereas @microsoft/tsdoc is just the parser). They use the TypeScript compiler engine to crawl your library's API, and then generate a documentation web site based on your doc comments. API Extractor 6 has already integrated the TSDoc parser.

[octogonz]

One possibility would be a compiler feature (or plugin?) that emits JSDoc type annotations in the output .js files, based on the compiler's type analysis. (I suspect this is closely related to another recent discussion, where people wanted the compiler to read plain .js files and generate .d.ts files based on its analysis.)

If the TypeScript source code has TSDoc comments, then in this approach the compiler would need to combine the TSDoc documentation with the type annotations to produce a JSDoc output.

It's tempting to expand the TSDoc language to optionally support every last JSDoc type annotation, and then the @microsoft/tsdoc library could be used to emit the JSDoc. However I'm sure there already exist plenty of specialized libraries for generating JSDoc, which do that very well, and are focused around that scenario. Keep in mind the goal is maximum compatibility with legacy JavaScript tools that are probably unable to adapt their parsers for this scenario. So I wonder to what extent the TSDoc input really needs to be consistent with the emitted JSDoc output.

What do you think? If someone has firsthand experience with this scenario, maybe they could provide some details.

[liamross]

Hey thanks for extending this into an issue! Let me just elaborate a bit on what a dream scenario would be for me personally. Here's an example from the playground, but with typing included in the TypeScript. Note that as you mentioned above, ideally the typings would not be repeated in the actual documentation:

/**
 * Returns the average of two numbers.
 *
 * @remarks
 * This method is part of the {@link core-library#Statistics | Statistics subsystem}.
 *
 * @param x - The first input number
 * @param y - The second input number
 * @returns The arithmetic mean of `x` and `y`
 *
 * @beta
 */
function getAverage(x: number, y: number): number {
  return (x + y) / 2.0;
}

And here is an example of the documentation that said code would generate:

---

Summary

Returns the average of two numbers.

Parameters

Name	Type	Description
x	number	The first input number
y	number	The second input number

Return Value

Type	Description
number	The arithmetic mean of x and y

Remarks

This method is part of the Statistics subsystem.

Modifiers

@beta

[liamross]

What I'm not sure about is whether that would be unreasonably difficult to implement, or whether that is even a requirement / goal of this project.

[octogonz]

@liamross Hrmmm... I'm a little confused by your latest comment. What would the expected output look like for the .js files?

I'm reachable on Gitter if you want to chat directly.