JSDoc. JavaScript: The Useful Parts

Photo by Rowan on Flickr

JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor. You add documentation comments directly to your source code, right alongside the code itself.

I use JSDoc more than 4 years and found it extremely good and useful. Documentation is important to have in a project. It helps you to save time for remembering, teaching newcomers, support. The project may have different types of documentation. As an engineer, the important part of the documentation is code documentation and JSDoc solves that problem as well.

Simple example

From the simple example, you may simply and fast understand what parameter’s types are function takes. You should not look inside the function for that. More often functions, methods are more complicated and it takes time to jump into the function and see what parameter’s types are.

Good example

Here you may find detailed documentation for a module. Just try to go through and if you do not understand what the module does we may have a call ☎️

shystruk/famulus_famulus - JavaScript library that provides a useful functional programming helpers. Add your own 👍_github.com

**Type annotations (**Type Checking)

One of the most powerful features that I like in JSDoc is types checking. It works perfectly in WebStorm. It won’t replace a TypeScript but after you get used to writing JSDoc you will stop be worrying about types and most important you are not needed to waste time on any configuration part.

WebStrom

So, here you may see that WebStorm highlights which argument is not fitting assignable type. It helps to avoid bugs with types and most importantly save time.

VS Code

VS Code allows you to leverage some of TypeScript’s advanced type checking and error reporting functionality in regular JavaScript files. This is a great way to catch common programming mistakes. These type checks also enable some exciting quickfixes for JavaScript, including add missing import and add missing property.

For VS Code you should add //@ts-check in each file if you want to have that.

JavaScript Programming with Visual Studio Code_Get the best out of Visual Studio Code for JavaScript development_code.visualstudio.com

👏 Thank you for reading. Suggestions, comments, thoughts are welcome 👍

If you like this, clap, follow me on medium, twitter, github share with your friends 😎