[stevebmark]

JSDoc comments are definitely not the “best of both worlds,” they are a limited and verbose subset of typing. I would only use them for specific reasons, like I’m in a hostile ecosystem that dogmatically doesn’t want any build steps (like WebGL/WebGPU engines).

[graftak]

It’s also really nice to have annotations describing what a function or object does, consuming a library is considerately worse without them, as they often prevent the need for looking up documentation, and they can even link to the right documentation page (although that is very rare).

When I write them I don’t annotate types though, that’s already done by typescript, and editors like vscode even gives you type hints in a js file if it detects d.ts files in the source.