Typescript: Add capability of transforming and emitting JSDoc comments

[ghost]

So I am trying to create a new documentation generator for TypeScript together with @BurtHarris. Currently it does not do much; I've been mainly tinkering a bit with the compiler API to see what it is capable of. You will be able to find it here when it's finished.

One of the things we thought about was the ability to 'target' JSDoc comments using the type information provided by TypeScript. I've been investigating how to tackle the issue. Ideally, it would use the transformers the compiler API has to offer but of all the functions provided in factory.ts, the ones that came closest were addSyntheticLeadingComment, setSyntheticLeadingComments, setSyntheticTrailingComments and addSyntheticTrailingComment; none of which provide the means to create complete synthetic JSDoc tags and comments.

So with this issue I'm actually asking the status-quo of this feature. Is it still possible to get this on the roadmap? If so, can I help? If not, is there a possibility of a patch that makes it possible to implement this as a third-party module?

Related issues

• Generate doc comments in emitted JS
• Cannot add or modify JSDoc with custom transformers
• Expose public API for transformation
• Replace emitter with syntax tree transformations and a simplified node emitter

Previous attempts

• spatools/ts2jsdoc
• develar/ts2jsdoc

[ghost]

I think we've found a way around it by using ts.createSynthesizedNode directly. Closing this issue for now.

[ghost]

I'm re-opening this as I would like to know if someone of the TypeScript team would accept pull requests for this feature. I've tried implementing it as a third-party module, but I need access to some private functions and currently it's not doable because JSDoc comments are not emitted (as far as I can see). I'm guessing this would require refactoring the comments.ts source file.

I also created a branch with a small example demonstrating how the explicit return type of a function could be added as a JSDoc comment.

[rbuckton]

We are discussing what changes we could make to comment emit to allow this. We already scan comments and often parse JSDoc comments for nodes. One option we are considering is reifying all comments in the compiler and storing them on Node, which we could then make accessible to transformers.

This would go a long way to simplifying comment emit in the emitter, but we need to balance this against the additional memory overhead associated with storing comment ranges for all nodes.

[weswigham]

@sandersn didn't you change our APIs recently to happen to fulfill this request?

[liyikun]

@rbuckton
Is there a new api to add the ast node of jsdoc?

[liyikun]

I think we've found a way around it by using ts.createSynthesizedNode directly. Closing this issue for now.

@samvv hi ，I am currently doing generate a ts code using JSON , I hope I can add jsdoc to ast node .but ts not support similar addSyntheticLeadingComment method, Do you have any good ideas here?

[ghost]

@liyikun Hmmm, been a while since I played with this. Unfortunately, I don't know how to create a synthetic node in the current version of TypeScript. I only know of https://github.com/microsoft/tsdoc, which covers my use-case.

[Jack-Works]

ts.createSynthesizedNode

Hmm sorry but it is no longer exists anymore. So how can I transform a JSDoc comment now?

[alanhoff]

it's possible to emit jsdoc nodes using ts.factory.createJSDocComment, example:

https://gist.github.com/alanhoff/b1a2ed871cf7046ca1f2f3c9e0bae1aa

[nonara]

it's possible to emit jsdoc nodes using ts.factory.createJSDocComment

Is this new as of TS 4? And are there any issues with transform?