Support 'Promote JSDoc comment to type annotation'

[danquirk]

We should consider the feasibility of a simple editor command where existing JSDoc comments are automatically converted to TypeScript type annotations. This could be a massive benefit for easing migration from JavaScript to TypeScript both in terms of saving pain fixing 'errors' (ie places that need type annotations) and being able to immediately leverage TypeScript's biggest value prop.

In addition, this could be a great way to improve the .d.ts generation process. Imagine picking up a new JS library that doesn't have a .d.ts but is well documented with JSDoc comments. Despite the lack of a .d.ts on DefinitelyTyped you could simply use this new command to promote the JSDoc comments to type annotations, then run the file through tsc --declaration and in almost no time have a high quality .d.ts.

---

Edit by @DanielRosenwasser:

• Teach the parser how to parse full JSDoc format.
• Emit JSDoc in .js files
• Display a warning when users use a JSDoc type annotation instead of a TypeScript type annotation.
• Support a tool/mode to generate a .d.ts from a .js file
• In the language service, JS doc could be used to infer types for .js files.

[mhegazy]

I like the idea; but I thik we should break this into pieces:

• Teach the parser how to parse full jsdoc format.
  This is full fledged support; parse diffrent variants, report diagnostics for wrong syntax... etc.. We sold report errors for param documentation that does not match signatures for instance; possibly as a warning.
  This also allows us to do better jsdoc intellisense, rename documentation when we rename declaration, atomatically creat doc comments and fix issues with doc comments.
• in typescript files, it would be an error to add type annotations in jsdoc for Parameters or return types.
  We can then add a light pulp quick fix to "add a type annotation". And this would be your migration story. Start with documented js code run a quick fix and voila! You have ts code.
• emit jsdoc in js files
  Users have asked for this multiple times. If we are parsing and understanding jsdoc, it should be trivial to fill in type information and generate full fledged Jsdoc for output js, we would do that under a --generatJSDoc flag. This also allows other tools in the tool chain, e.g. Closure compiler to do better optimizations.
• support a tool/mode to generate a .d.ts from a .js file
  This would be built on our support for jsdoc, and use these to generate types as good as it can, along with possibly tweeked inference algorithms to get you started. I believe it is important to treat this as a separate step to allow users to twerk the resulting .d.ts after the initial generation as the process is inherently lossy and we have no way of doing it right all the time.
• finally, in the language service if you are in a is file, jsdoc would be used to infere types.
  I believe this is not contravetial and fits with the migration story stated above.

[teppeis]

support a tool/mode to generate a .d.ts from a .js file

I created closure-ts that is d.ts generator from JSDoc typings.
It generates closure-library.d.ts from Closure Library that is fully typed with JSDoc annotation.

[danquirk]

I'm unsure whether we would want to do something like give an error on certain JSDoc comments in TypeScript. It seems plausible that people would still want those comments for some other system in their build pipeline but perhaps not.

[mhegazy]

@danquirk that is why i was saying 1. make it a warning not an error, and 2. emit type information in jsdoc. so it is an error to include the type in a .ts file jsdoc, and the compiler will put in the correct type when it writes out the jsdoc.

[DanielRosenwasser]

I adapted @mhegazy's list to a task list in the original comment. @CyrusNajmabadi can check off anything he's already worked on. I think the first item has been taken care of.

[aozgaa]

Regarding the first step, it appears https://github.com/jsdoc2md/jsdoc-parse already provides some of the facilities for parsing JSDoc, though it additionally gets type information from declaration signatures. Perhaps rather than re-writing the tool for our own purposes we could contribute and add a PR for an API?

EDIT: using that tool would likely be inefficient as it requires a second scan of a sourcefile for the tool and it's unclear how to extend it for live-editing. oops.

[rgbkrk]

Perhaps rather than re-writing the tool for our own purposes we could contribute and add a PR for an API?

That would be so great to see adoption within the community. 😄

[RyanCavanaugh]

Lots of work to do here. @aozgaa is doing some of it; we'd take PRs on other parts. This can be an area of incremental improvement

[mhegazy]

Most of the work outlined here has been covered by #4789