I hope you have tried using it in decent-sized projects and not just talking about a theoretical option.

What I felt using typescript style jsdoc with react is that its much more verbose and repetitive, features are lagging, less safe, and most importantly, simply not powerful enough (because of being a line comment). It’s the only option though, for teams who don’t want to go full .ts

For eg., you can’t provide type annotation for expressions/parts within a statement, like generic values or typecasting a expression.

Like try converting `export default connect<TypeA, TypeB>(A, B)(SomeComponent)` or `(a.something as string).toLowerCase()` to jsdoc.

It is doable with plain js logic/code, but in react components (due to its somewhat dynamic nature) generics become very important (for type safety).

Tooling with jsdoc is half-baked — try writing a interface with multiple properties in jsdoc (multi-line comment for the type definition) and the syntax highlighting breaks.

Also, in general — refactorings tend to add a lot more type info because when you move some lines from one large function to multiple smaller function, now even though the caller implicitly knows the parameter types, the function has to explicitly mention it. That’s understandable if the function is being called from multiple places, but if you are using it just as a encapsulation for a bigger logic (i.e. Called from one place), it gets frustrating and causes fiction during refactoring.

I think its great that TypeScript even has the flexibility of using it in jsdoc style, but it’s not all shiny on this side. Also, the community is smaller (using jsdoc style), so it’s hard to know the pitfalls and success stories without jumping into the bandwagon.

Hi, I am abhas — another one of those frontend developers :) More at https://bendtherul.es

Hi, I am abhas — another one of those frontend developers :) More at https://bendtherul.es