JSDoc: Improve your JS code documentation

In the dynamic world of JavaScript, good communication is just as crucial as writing good code.

This is where JSDoc enters the scene, a tool that's essential for any JavaScript developer aiming to elevate the readability and maintainability of their code.

JSDoc helps you craft a clear, navigable guide through your code for others and for your future self.

Let's get started and see how JSDoc can make your projects more accessible and your development process more efficient! 🔥

What is JSDoc?

JSDoc is an open-source documentation generator used by developers to annotate JavaScript source code.

By using comment blocks specific to JSDoc, developers can provide rich, insightful descriptions of the code's functionality, parameters, return types, and more.

This isn't just about adding comments; it's about creating a comprehensive guide to your code.

For example, in the image below, we are able to give a short description of what a function does, what are its params and what is returned.

Why use JSDoc?

Using JSDoc can be good for your project for several reasons, let's go through a few of them:

1. Improve code readability: JSDoc provides a clear overview of what a function or a module does, what parameters it expects, and what it returns.
2. Help code maintenance: When code needs to be updated or debugged, JSDoc can help developers quickly grasp the purpose and functionality of the code, reducing the time needed for maintenance.
3. Support for Intellisense and Autocomplete: Many code editors and IDEs (like VS Code) use JSDoc comments to provide Intellisense and autocomplete features. This helps developers write code more efficiently by giving them quick access to function signatures and parameter information.

Setting Up JSDoc

JSDoc is available as a Node.js package, which means you can easily install it using npm, the Node package manager.

If you want to install it globally, run:

npm install -g jsdoc

If you want to install it in your project, run:

npm install --save-dev jsdoc

Once it finishes installing, the next step is to set up a basic configuration file. This file is the jsdoc.json, and it defines the rules and settings. Here's a simple setup:

{
  "source": {
    "include": ["src"],
    "includePattern": ".+\\.js(doc|x)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "opts": {
    "destination": "docs"
  }
}

To generate documentation, you run JSDoc from the command line with:

jsdoc -c jsdoc.json

And... boom! There will be an index.html file with the docs. But if you are following along and you opened the index.html file, you'll see that it's EMPTY!

And why is that? Because first, we need to write the JSDoc comments and then run this command. So let's go ahead and understand how to do this!

Writing JSDoc Comments

A JSDoc comment begins with /** and ends with */. Within this, you use specific annotations, each beginning with `@, to provide structured information.

Let's start with a sum function, a simple one that takes 2 numbers and returns another number.

We will use the @param to describes a parameter passed to a function with its type and description, like this 👇

But we are missing something. This function returns a number. So let's specify that with @return or @returns, like this 👇

However your code is growing (like a real software project), and now you want to move that sum to a class. Let's define with @class like this 👇

And what if that class has a function that can throw an error, we will use JSDoc to describe it with @throws like this 👇

And last thing, what if you create a new sum function and deprecated the old one? Use @deprecated like this 👇

These are some of the annotations that can be used with JSDoc, to see all the available, check here.

Generating Documentation with JSDoc

Great, now our JSDoc comments are in place!

So simply run the command jsdoc index.js in your terminal, replacing `index.js with the path to your JavaScript file. JSDoc will process the comments and generate HTML documentation.

💡 If you created your jsdoc.json in the section above, you can run with that!

Customizing the Output

JSDoc allows customization of the output documentation through:

• Templates: JSDoc supports various templates to change the layout and style of the generated documentation. You can choose a template that fits your project's needs or even create a custom one. Check them here.
• Styling: The generated documentation's CSS can be modified for further customization.

Integrating JSDoc into Your Build Process

You can integrate JSDoc into build tools like Grunt, Gulp, or Webpack. This can be done by adding a task or script in your package.json file or build configuration file.

And you can even integrate it in a CI/CD pipeline, set up a step that runs JSDoc to ensure up-to-date documentation is generated with every build.

Conclusion

In this guide, we've explored the essentials of JSDoc, from setting it up and writing effective comments to generating and customizing documentation.

JSDoc is a powerful tool that enhances the readability and maintainability of JavaScript code, ensuring that every function, class, and module is clearly understood.

Thanks for reading! Follow to get more of this type of content. Have a great day, see you soon! 👋