Comment by WebReflection
2 years ago
JSDoc TS is well documented: https://www.typescriptlang.org/docs/handbook/jsdoc-supported...
It's not 1:1 in features though, but because you can import definitions https://www.typescriptlang.org/docs/handbook/jsdoc-supported... you can use a file a part whenever you encounter any of those advanced features / edge cases current JSDoc does not support.
Like other said, it's still TS after all, and there are escape hatches when needed.
In so many projects I use JSDoc TS, the amount of projects that ended up needing a manual .d.ts file not utomatically generated via `tsc` can be counted in half hand.
Maybe people could give it a try, after all if you comment a method, beside its signature and return types, you can as well just move types in there ;-)
That's an interesting hybrid approach, thanks Andrea.
Is this what Svelte will use? (Asking anybody that knows, of course.)
Anyway, to me the main problem in using TS with libraries is that we have 3-4 major releases per year, and they're just too many. Unless one takes a very restrained approach, releasing very generic (and thus less helpful) types that won't (presumably) break future (or past) versions of TypeScript, we need to release with `typesVersions` targetting n different versions of TypeScript. That's an ever-growing bother indeed for maintainers as time passes.
And I fear the hybrid approach above won't escape this issue. So using "pure" JSDoc or JSDoc with just a sprinkle of TypeScript actually makes sense... But I'd expect this workflow to be winning with smaller projects, and that's why this announcement for Svelte has been surprising to me.