Documentation tags have a machine readable structure.
That structure can be parsed and used for documents, editor hints, diagrams, and even type check validations.
Instead of having to traverse the entire callgraph of a function to have an idea of what guarantees it provides, you simply read the documentation tag.
This is O(1) instead of O(V+E) where V are the functions and E are how you call them.
> Instead of having to traverse the entire callgraph of a function to have an idea of what guarantees it provides, you simply read the documentation tag.
> This is O(1) instead of O(V+E) where V are the functions and E are how you call them.
Unless of course it is wrong, because it is just a convention for a comment and not actually an enforced type.
The wrong direction is: less information, no stable contracts, forcing people to guess, complete chaos and anarchy, make up your own format with your own tags that nobody supports.
My comparison was between:
- JavaScript with no documentation tags
- JavaScript with non-machine readable documentation
- JavaScript with documentation tags
They are (mostly) not for you.
They are for the tooling, including your editor, to detect that your declared foo(bar: string) but you're calling it as foo(5).
The value of JSDoc is the same as value of TypeScript: add static types to your code to detect bugs.
And yes, it works in practice.
I started using JSDoc quite recently.
I don't enjoy adding those type annotation comments but undeniably they (and VS Code tooling, jsconfig.json) detect errors that, if not fixed, would end up blowing up at runtime and causing me to spend more time fixing them.
Again, maybe just me. But, my brain doesn't parse them unless the code is already extremely well structured. In which case, why include annotations at all? Or in other words, isn't it always better just to improve the readability of the function itself?