Late to this party, wanted to add something here. Wholly agree with your perspective.

The counter-trend to this is the structural-first approach to TS, which eschews return types, and uses mechanisms like the 'satisfies' keyword to ensure that the type evaluates against known symbols, while maintaining the language-server inferred type product in all contexts. The tl;dr goal of this method is to make code that presses compiler-safety at every edge.†

Inversely, the JSDoc method sees you explicitly define everything, and what you save is writing a d.ts file (sometimes). You can pass the TS compiler over it, but it's not going to give you the incremental typing benefit. What you get are a bunch of black boxes with a published contract and a pretend-really-hard approach to typing.

That is frequently fine in cases like libraries. What I worry about is your average dev†† assuming this objectively traction-control-off approach to writing JavaScript approach is good, or rigorous. I don't doubt the svelte team is perfectly capable of writing code in this mode of delivery, and has an armada of tests to back up the proposition. The average dev always opts for easy, and therefore will take to this approach with gusto, but balk at the testing that is necessary to make up for some of the blackbox behavior (blind calls, function internal any, implicit unknown passing that TS would reject, et al) that may not be fully consistent with the behavior the purported type signatures suggest.

†for the sake of argument, I'll define "average dev" as people with a few years of experience still feeling out their place in the industry, and the 9-5 contingent who may or may not own a computer at home and like that paycheck.

††I don't necessarily rep this approach, it's just the other extreme*

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 ;-)