Suggestion: Generate doc comments in emitted JS

[RyanCavanaugh]

Support some level of automatically generating doc comments for non-TypeScript JavaScript consumers.

Need more details on what exactly people would like to see generated.

[jvilk]

Most importantly, for me: Propagate type information into existing JSDoc comments. This would allow me to use existing JSDoc documentation generators to produce nice looking HTML documentation for my TypeScript libraries without respecifying type signatures in JSDoc comments.

(Of course, constructing a mapping between TypeScript types and JSDoc types might end up being nontrivial, especially where interface types are concerned.)

[jmatthiesen]

Making sure I understand you correctly - you'd like to see the type information from TypeScript persisted into JSDoc comments in the generated .js files from your TypeScript, right? Can you give an example of a documentation generator you currently use?

[jvilk]

you'd like to see the type information from TypeScript persisted into JSDoc comments in the generated .js files from your TypeScript, right?

Correct.

Can you give an example of a documentation generator you currently use?

I am not using a documentation generator at the moment (because it would be infeasible/frustrating to maintain type information in two locations as the code evolves), but I would like to use something like JSDoc: http://usejsdoc.org/

[sebastian-lenz]

I've created a documentation generator that can directly parse *.ts files and that understands TypeScript elements like classes or types. Maybe you would like to check it out:
https://github.com/sebastian-lenz/typedoc

[jvilk]

Your tool looks really nice! I'll have to see how it holds up to my code.

I figure it would be more elegant to avoid needing to maintain a separate project if we could find a decent mapping from TypeScript types and JSDoc annotations, but maybe that is a rathole in-and-of-itself.

[fsoikin]

We have a similar tool, but with a bit broader scope. It uses a template engine to generate output, which makes it perfectly usable for generating docs. Granted, there is more work for you (have to write the templates), but then you can make the output nicely customized.

Check it out: http://github.com/erecruit/TsT

[herrernst]

As the issues on Codeplex are now closed, I'd like to link to the JSDoc request there: http://typescript.codeplex.com/workitem/1596
IMHO, JSDoc annotated output would not only be good for documentation generators but also for other tools.

[mixtur]

+1 to herrernst
It would be nice to have JSDoc in emitted code, not because it would be easier to read later, but because such code can be feed to Google Closure compiler.
Generating already optimized code is another alternative.
Sorry for bad English.

[electricessence]

+1

[ghost]

Yup, annotations for the google closure compiler are a must for me. Having to do it manually really limits the advantages of typing. If you get your manual declarations incorrect, it can lead to incorrectly optimized results.

As far as the "needs proposal" tag goes.. do this please :) -- https://developers.google.com/closure/compiler/docs/js-for-compiler

[mirhagk]

In addition to the JSDoc comments, it may be worth looking into also supporting the exports and externs for the Google Closure Compiler
https://developers.google.com/closure/compiler/docs/api-tutorial3

EDIT: Emitting export and externs for Google Closure is mentioned in #8

[zzo]

+1 for closure-style type comment annoataions

[mindplay-dk]

I believe this feature would weigh in huge, as far as convincing established JS projects to "upgrade" their codebases to Typescript, since, effectively, this would eliminate the need to hand-write JSDoc annotations, while resulting in JS code (for plain JS consumers) of the same quality - or higher, for that matter, since Typescript annotations as well as code all gets checked at compile-time. In other words, this would save time and increase quality.

As things stand, without this feature, some JS project maintainers may well hold back, because they don't want to lose their establish plain JS consumer base, a lot of whom depend on annotations for IDE support.

(of course, IMO they should all "upgrade" to Typescript, but I'm obviously opinionated ;-)

[evil-shrike]

+1 for emitting jsdoc tags with type info as much as possible.

[hraban]

I'd like to take a jab at this. Can somebody from the TS project weigh in on the expected amount of work this would require? From an outsider perspective this looks suspiciously easy.

Do you foresee any major roadblocks? Or do you expect this to be as easy as it looks (slightly amend the last "code generating" compiler phase)?

[CyrusNajmabadi]

Hey @hraban, this should not be too much work. You'd basically just need to:

1. Add a compiler option for this.
2. Fix up the emitter to respect the option.
3. The Emitter should likely generate this information for everything we emit, and it should either augment an existing comment we are writing out, or it should add a new comment if none already exists.

[TobiaszCudnik]

There's also the difference with nullability. For the full closure compiler
support you may want to infere the assertions and if conditIons.

On Friday, April 17, 2015, CyrusNajmabadi notifications@github.com wrote:

Hey @hraban https://github.com/hraban, this should not be too much
work. You'd basically just need to:

1. Add a compiler option for this.
2. Fix up the emitter to respect the option.
3. The Emitter should likely generate this information for everything
   we emit, and it should either augment an existing comment we are writing
   out, or it should add a new comment if none already exists.

—
Reply to this email directly or view it on GitHub
#10 (comment).

Tobiasz Cudnik
Software Developer @ Voiceworks
http://voiceworks.com

[mhegazy]

@TobiaszCudnik I would consider this a different feature. I would also argue this has to be only supported for explicit types only not infered ones.

[danquirk]

Note IntelliJ's generation of JS Doc comments includes information about inferred types (in particular, inferred function return types).

[mhegazy]

Doing only declared types allows to implement this as a syntactic transformation, which is a. simple, and b. works for single file emit. It also allows users to manage what there public API (assuming that this is what it is used for).

[hraban]

Hey guys! I'm sorry but I am absolutely swamped at the moment. It's in the back of my mind, but on hold for a while. Definitely interested to see whatever happens once this gets picked up, though!

[ustims]

This is very outdated, but probably could be helpful: https://github.com/evanw/typescript-closure-compiler

[hraban]

Hello everyone,

I've been looking around the relevant code recently and going through the comments here.

I agree with the "we should extend existing JSDoc comments" point, eventually. It makes the most sense from an integration-with-current-tools perspective, and it would be a nice selling point, as the resulting JS would then be JSDoc consumable with automatic type annotations from TS.

This leads to situations like:

/**
 * Determine the logarithm of a number to a specific base
 *
 * @param b The base of the logarithm
 * @param {weirdType} g The number to determine the logarithm of
 * @return The logarithm of g in base b
 */
function logB(b: number, g: number): number {
    return Math.log(g) / Math.log(b);
}

Where, ideally, you would want this as the output:

/**
 * Determine the logarithm of a number to a specific base
 *
 * @param {number} b The base of the logarithm
 * @param {weirdType} g The number to determine the logarithm of
 * @return {number} The logarithm of g in base b
 */
function logB(b, g) {
    return Math.log(g) / Math.log(b);
}

In that case, we'd need not only a proper JSDoc parser, but also a JSDoc serializer.

Right now, JSDoc is not even parsed, at all, in .ts files, only in .js. We can enable it for .ts files, but that still leaves the problem of "changing" the comment before output; the comments are just copied verbatim from the source file, not rebuilt from a "jsdoc AST" as it were (even though they are properly parsed that way).

So this would seem non-trivial. What are your thoughts on this, so far?

There are a few ways around this, just to "get started", some quick and dirty solutions to get more than what we have right now, with less effort than the above. One option is to completely ignore nodes with existing JSDoc comments, hidden behind an appropriate flag, e.g. --generate-missing-JSDoc. It's not pretty (disincentivizes creating JSDoc by users), but it's a start. Ideally this will get us closer to a full solution.

What do you think? Did I misunderstand something from the code, perhaps? I'm curious to hear what people who are more familiar with the code structure have to say about it.

Regards

Hraban

[mhegazy]

@hraban you are right, we will need to 1. parse jsdoc in .ts files, 2. Emit the jsdoc correctly from the AST and 3. Augment the jsdoc with type information if the jsdoc already exist.

1, is fairly trivial and so is 2. 3 needs some synthetic nodes to be created, but should not be thst complicated either (I belive it should be done as a syntactic transformation and only for explicit type annotations and not infered types).

If this is something you would like to contribute, I would be happy to help out as much as possible.

[DanielRosenwasser]

@mhegazy, isn't @aozgaa working on something similar?

[hraban]

@DanielRosenwasser Ouh, if that's the case then it's good to know now :) I sent Arthur an e-mail to ask him about it.

@mhegazy:

1. If all you want is information that is used by the compiler, then this is indeed trivial. Remove the if-guard at if (isJavaScript(fileName)) { addJSDocComments() } in parser.ts, and you have augmented the AST with JSDoc.
2. However, addJSDocComments is incomplete. It ignores JSDoc elements that are not param, return, returns, type or template. If you use the parsed AST to serialize a JSDoc comment, you will lose all other tags. I think (?). Is that okay?
3. I'm not religious about it, just fmi: why do we not want inferred types?

Thanks for offering help, I'm exploring what needs to be done for this and I might take you up on that offer. :)

[mhegazy]

@aozgaa is working on jsdoc tooling in the language service. so this is up for grabs.

@hraban

However, addJSDocComments is incomplete. It ignores JSDoc elements that are not param, return, returns, type or template. If you use the parsed AST to serialize a JSDoc comment, you will lose all other tags. I think (?). Is that okay?

I do not know, what other tags we need? do you have a list in mind? i think we should be adding them as we go, or just add a catch all generic tag that would be available in the tree but ignored by tooling cause they do not understand them. @CyrusNajmabadi would have better ideas here.

I'm not religious about it, just fmi: why do we not want inferred types?

1. simplicity, no checker/ type involvement. 2. fits what we have been doing so far, of no type-directed emit. and 3. works when you are using ts.transpile, i.e. as a single file syntactic transformation and 4. (more of me pontificating) i think if you did not bother to put a type annotation, it should not be in your API, if you want it to be, may be you should think about it and explicitly specify it.

[Oceanswave]

+1

[alexeagle]

wow issue #10 so few digits

I see comments here about emitting docs for Closure Compiler, without much mention that for complex types the translation between the two type systems is non-trivial and lossy. Now that TypeScript will have nullability it's improved a bit.

@martine on our team works on Tsickle which produces closure-compiler-compatible TypeScript code that can down-level to ES6 with goog.module module syntax, and has a (presently incomplete) typed mode to carry forward the type information. https://github.com/angular/tsickle

[evmar]

Related: #7393 is the smaller feature request, specifically to expose the compiler's JSDoc parser API for tools like documentation extractors.

Tools like TypeDoc currently must have their own separate parser for JSDoc on top of the TS API:
https://github.com/TypeStrong/typedoc/blob/2e855cf8c62c7813ac62cb1ef911c9a0c5e034c2/src/lib/converter/factories/comment.ts#L78

[claytonsilva]

+1

[develar]

As TypeDoc has a lot of errors and cannot compile fully correct project, ts-jsdoc was implemented. (https://github.com/develar/ts2jsdoc). It allows you to use any jsdoc template. And reuse all features that jsdoc has. No need another special tool for TypeScript (e.g. JSDoc supports interfaces).

generated jsdoc annotated js file

generated docs

Only public TS API is used, any compilable project is supported. Currently, tested only for node modules. And function (callback) types are not supported (planned).

[JasonKleban]

@RyanCavanaugh - Can I ask what is the current state of this? Preserving type information through to jsdoc-consuming documentation generators is a sticking point for my team's adoption of Typescript in a environment that requires supporting non-typescript project groups.

[kimamula]

I am trying to solve this with custom transformers, as it looks like that the feature exists exactly for solving this kind of problem.

However, I cannot find how to mutate ts.JSDoc with custom transformers.
There's no method like ts.updateJSDoc().
ts.updateMethod(), for example, does not accept a parameter of ts.JSDoc type.
https://github.com/Microsoft/TypeScript/blob/1db4f96fd14fc3de5ae3704e925afd6474cfb8f5/src/compiler/factory.ts#L582
I also tried to directly mutate ts.JSDoc which is obtained by iterating over children of ts.MethodDeclaration, which had no effect in the emitted JavaScript.

Is it possible to mutate ts.JSDoc with custom transformers?

[aoberoi]

I would really love to see JSDoc comments in the emitted .js. I consider updating the comments in .ts files a "nice to have" feature, but not truly necessary, since documentation generators could be run on the emitted .js instead.

I believe solving this issue would really further the TypeScript team's story about being able to adopt the language incrementally and its compatibility with the existing JavaScript ecosystem (as opposed to forking the community and building separate tools).

[DrMiaow]

I would be using more TypeScript, but I need the full functionality of JSDoc. I am actually in the process of converting one of my experimental projects from TypeScript to ES6 simply because I need JSDoc documentation more than I need the features of TypeScript.

[leidegre]

I would like to add that the Google Closure Compiler might be able to leverage such JSDoc tags to produce a smaller file size. Since I know the topic of minification has been discussed before with respect to the superior type information available to TypeScript, this would seem like a two birds with one stone opportunity.

[piranna]

Is there any progress on this? I would be very interested on add/augment JsDoc comments on Javascript files with types inferred by Typescript :-)

[Shubham-raut]

+1

[geekley]

Agree that this should be done by typescript compiler as part of the compilation process, there's no sense in trying to implement this using some external tool or additional compilation step.

Any improvements in this area are valid, even if not all TS types/constructs have a JSDoc equivalent, it's fine adding just the simple ones that do at first. The emitted JSDoc can slowly improve over time without worrying about backwards compatibility, since it's just a comment in a generated file.

I was unsure if I should open a new issue but ... I'd like to propose a few things:

---

I propose an option like "emitTypeAnnotations": "JSDoc" in tsconfig.
Obviously, those emitted comments shouldn't be affected by "removeComments": true.

We should make this (at first) specifically ONLY about emitting TS types -> JSDoc /**@type{T}*/ annotations where : T is present in source TS. No new type info needs to be added (what can be inferred in TS can also be inferred in generated JS anyway). It's just for type info from TS that would be lost in transpilation - mostly things not inferred, like parameter types, etc. Types already inferred in TS (e.g, return values), don't need to be added to JS.

Only later we could think about optimizations, like:

• you may not need to add it if a JSDoc from TS will already be copied to the generated JS with the type information (e.g. @param)
• you may not need to add it if it would be inferred (when : T in TS was redundant).

💻 Use Cases

• Better error-checking in JS without needing configuration to relax strictness in type-checking.
• Less dependency on source maps, .d.ts, online APIs, etc., when inspecting only a generated JS (e.g. from some library).
• Easier to migrate from TS projects to pure JS; specially while https://github.com/tc39/proposal-type-annotations is not implemented (that could take forever).
  • When this proposal is implemented, you can reuse the setting like "emitTypeAnnotations": "ESNext"
• Much more useful emitted JS wrt. compatibility with other type systems (Flow, Closure) and existing tools.

📃 Motivating Example

let ctx: vscode.ExtensionContext;
export async function activate(context: vscode.ExtensionContext) {
}

Could simply become something like:

/**@type{vscode.ExtensionContext}*/ let ctx;
async function activate(/**@type{vscode.ExtensionContext}*/ context) {
}
exports.activate = activate;

Then ship just the JS. No source maps, no .d.ts, etc.

🔍 Search Terms

emit jsdoc type generated

[mindplay-dk]

How is the parity of JSDoc with TS these days, feature wise? How accurate could the emitted types be?

[mahnunchik]

I would like to have JSDoc comments in generated js.

[piranna]

We should make this (at first) specifically ONLY about emitting TS types -> JSDoc /**@type{T}*/ annotations where : T is present in source TS. No new type info needs to be added (what can be inferred in TS can also be inferred in generated JS anyway). It's just for type info from TS that would be lost in transpilation - mostly things not inferred, like parameter types, etc. Types already inferred in TS (e.g, return values), don't need to be added to JS.

I think inferred types would make sense, but agree can be seen somewhat superfluous, so I would left it as an option.