[alangpierce]

I guess depends on exactly how you use JSDoc, but it sounds like you're talking about relatively informal documentation with some best-effort machine validation. My experience is that you don't get anywhere close to the confidence that you get with a real typechecker. Docs can be overlooked, docs can be misinterpreted, docs can get out of date, docs can be wrong by mistake. And, inevitably, if you have many people working with the same code over the course of years, these issues will be common. Having an actual typechecker avoids all of these problems, at least for documentation of data formats.

If you do mean annotating all types with the thoroughness that you'd annotate TypeScript code, then really you're just writing TypeScript in JS, and TypeScript is a much more concise language than JSDoc for that.