Enough of JSDoc is good enough
After using JSDoc for some time, I want to summarize the topic. Share common problems that I myself faced.
From practice, I could say that it’s easy to over think the way you use JSDoc because it does not have any restriction rules on how to use it. So you may end up with many different ways. And often it does not end well for your productivity. To avoid problems with JSDoc, you need to understand what it wasn’t designed to be.
Table of content
- Do not use JSDoc everywhere
- Write tests instead of relying on JSDoc linter
- Rely on web documentation
- JSDoc for external usage
- Do not try to make JSDoc complex
- Use JSDoc with mostly TypeScript definition file
Do not use JSDoc everywhere
When using JSDoc often, you might start thinking of documenting not only functions used outside of your module, but everything inside. The reason being that it’s easier to write internal logic if everything is strictly typed. At least it seems this way. Next step might be to even share JSDoc between several applications like server side and client side, by including server repository as a dev dependency to client code. This way, you only write JSDoc once and then reuse it.
So, it is easy to cover everything with JSDoc and smartly reuse types in several projects. But is it worth the effort? JSDoc doesn’t protect your code from errors. It only shows warnings in your editor, but your code will still run in case of bad types. To really protect plain js, you need to check types in code. This is the only way.
So, if you’re using JSDoc to protect your code from errors, it might be better to consider strictly typed languages or using tips below.
Write tests instead of relying on JSDoc linter
When you decide to use JSDoc everywhere, you start overly relying on linter(tscheck option in case of VSCode). As I said before, it’s only the illusion of protection.
Instead you could cover your code with all kinds of tests. Better to spend time on testing rather than adding types to every internal function. Testing is a bullet-proof approach to monitor your code. JSDoc was not designed to do that
Rely on web documentation
Do not overly rely on typescript intellisense in VSCode or similar editors. I’ve seen a lot of cases when typing definitions of the library did not provide the correct definition. Better open the library’s documentation on the internet and select the version you are using. Keep it open and look at it if you do not remember something. Btw, not that long time ago I stopped using any intellisense at all and relying only on tests and web documentations.
JSDoc for external usage
This is where JSDoc shines. You wrote a library or an abstract module in plain JS, you covered it with tests. Next step is to create documentation. Annotate external api with JSDoc. Then you could use these definitions to generate markup documentation and host it somewhere or import the module in some other project and utilize intellisense tips. So, you describe only the external interface of your module with JSDoc. This is not time consuming and much better than no documentation at all.
Do not try to make JSDoc complex
Even though you could create as complicative types with plain JSDoc as you want, it quickly becomes messy in your comments. I find it much better to get the best parts of typescript(definition file) and JSDoc(ability to use in a plain JS project).
JSDoc with Typescript definition file
Have a single typings.d.ts file in the root of your project. Define as difficult types as you want there. Everything that typescript could do is available. Although, practice shows that complex types usually appear when you want to make abstract types to reuse in your internal logic. An example might be DB driver wrapper functionality that returns your models. I would not recommend using JSDoc with internal module logic. If you over think you, could spend more time on implementing abstract types rather than on writing logic itself.
Outer facing logic doesn’t need to be that complex because it usually operates with primitive types as arguments and return statements.
With typescript definition file, JSDoc plays role of glue between Typescript and plain js without a need to provide typescript transpiler step to project build flow
Keep it simple.
