JSDoc + IDE vs. TypeScript

Question

With a properly maintained JSDoc, almost any modern IDE can identify a type mismatch (of assignments, functions' signatures/arguments) and many other issues that a non-strongly-typed language introduces. Besides that, modern JS comes with a predictable variable scoping, hoisting-free behavior, modularization, built-in classes support, and many other.

In which scenario may TypeScript serve developer needs better than JS+JSDoc?

Answer 1

I think this is a little weird of a comparison. JSDoc is documentation oriented, while typescript adds optional static typing to js. These tools do have some parts in common, they allow for type checks for example, but their purpose is different.

It's an interesting question though. I'd like to encourage a discussion on the topic, so I'm going to talk from my experience with the tools.

The main issue I have with jsdoc is that the following part is crucial:

properly maintained JSDoc

The usefulness of jsdoc for autocompletion depends directly on the effort and quality of the jsdoc comments. I found it hard to enforce in big projects. Complex types/interfaces are also a pain to describe and maintain, being extremely verbose. Ts on the other hand is a lot more concise than jsdoc.

Furthermore, types and interfaces in ts are first class citizens, and aren't just an addition for documentation sake. They are entities in the source code and can be exported for other modules to use. Type mismatch is enforced in the compilation process(and before). There are also mechanisms like generics or decorators, that come with ts.

Back to the enforcing guidelines part. With ESLint you can setup flexible rules that will allow you to fine tune restrictions/styles/guidelines for your types. You want rigidly static types? Or you want leniency?
You can have your exact needs enforced and hooked up to ci/cd if you want. In my eyes that's a big bonus when working on big projects.

Tooling is also an important factor, both jsdoc and ts are mature enough to have ecosystems around them. Although at this point in time jsdoc isn't an active project, while ts is extremely popular and has a huge community around it with lots of activity.

So it all comes down to your needs, if you're happy with what jsdoc can do for you and documentation is your main focus, then ts won't do much for you.

P.S. Ts and jsdoc aren't mutually exclusive. You can have both, although you might want to switch to something like TSDoc