Repository navigation
Support 'Promote JSDoc comment to type annotation' #2916
Description
Activity
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.
- Teach the parser how to parse full jsdoc format.
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.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.
Reacted by Anthony CiccarelloDan Quirk (@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.
I adapted Mohamed Hegazy (@mhegazy)'s list to a task list in the original comment. Cyrus Najmabadi (@CyrusNajmabadi) can check off anything he's already worked on. I think the first item has been taken care of.
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.
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. 😄
- added this to the milestone
on Aug 5, 2015 Lots of work to do here. Arthur Ozga (@aozgaa) is doing some of it; we'd take PRs on other parts. This can be an area of incremental improvement
Most of the work outlined here has been covered by #4789
- removed this from the milestone
on Apr 26, 2018 - locked and limited conversation to collaborators
on Jul 31, 2018
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 Daniel Rosenwasser (@DanielRosenwasser):
.jsfiles.d.tsfrom a.jsfile.jsfiles.