Why use JSDoc
I could guess the most common error in JS is the one related to wrong type interpretation. It happens because JS plain objects is much more common than alternative in face of classes.
But wait, what about type checkers: typescript, flow. They are cool, but in most cases it’s overkill. To use them you need extra dependencies, the code should be compiled or somehow changed to be executable, they are taking extra time on setup. For bigger projects it might be a good idea to investment more time in all these casualties, but there are a lot of situations where its better to leave code simple.
Solution
My proposition is to use JSDoc as much as possible.
Pros
- Supported out-of-box in popular IDEs and Code Editors
- Widely used
- No extra dependencies
Cons
- Syntax is a bit weird
Example
Let’s talk an example.
Say, we have some asynchronous operation and then passing nested property to other calls. Very common situation. Object scheme could be complex. If so, it could cause errors or numerous manual docs checking
Let’s add some typing to it.
I am using VSCode with default configuration, no extensions. Here is what I see with default editor auto suggest
