JSDoc what is that?

Today, the documentation of an API is something that programmers often overlook, we prefer to go directly to write code and forget about the boring task of writing documentation. But for the luck of all, today we have tools that help us simplify this complex task of writing all the documentation of the code, and the best thing is that we do it without having to worry about having to spend additional time. JSDoc is a clear example of one of these tools, when working with JavaScript, this tool generates a great focus of attention.

What is JSDoc?

JSDoc is a documentation generator that is used for the Javascript language, we can compare it with Javadoc (JAVA) or PHPDocumentor (PHP) among others, JSDoc what it does is analyze all the Javascript code and AUTOMATICALLY 🤯 generates a static page (HTML) with All the documentation. JSDoc is easy to integrate with any IDE or Code Editor.

Installation of JSDoc

To use JSDoc you need to download and install it. This can be done by means of a NodeJs packet driver called NPM, by executing the following command in the terminal.

npm install -g jsdoc

When we execute the previous command, we perform the installation of JSDoc globally (-g), in case it is necessary to install it locally (that is, in a specific project) it must be saved in its respective package.json, to do this we execute the following command.

npm install --save-dev jsdoc

The documentation generated by JSDoc is created based on the comments within the source code, these comments should be placed just before the code to be documented. The comments have the following syntax.

/**
 * Function to add two numbers
 * @param {number} a
 * @param {number} b 
 */

They start with “/ **” and end with “* /”, then add * (asterisk) for each line before closing the comment, these lines are where we proceed to add the labels, JSDoc has a great variety of labels, which allows modify the documentation, we can count on simple labels for parameters of simple functions for very complex objects among others.

Fortunately, JSDoc has a great documentation that is very rich in content, in it we can see different ways of using tags, among other things, you can visit the JSDoc page directly here.

Before finishing, I think it is a good idea to be able to make an example of use so that we can understand the operation of this tool.

In a file called ops.js we will perform two functions, one to add two numbers and another to obtain the difference of the numbers; these numbers are received through the parameters “a” and “b”

ops.js

/**
 * Function to add two numbers
 * @param {number} a 
 * @param {number} b 
 */
function sum(a, b){
    return a + b;
}
​
/**
* Function to subtract two numbers
 * @param {number} a 
 * @param {number} b 
 */
function diff(a, b){
    return a - b;
}

We will add a script in package.json to be able to export to a static website

package.json

"scripts": {
    "build-doc": "jsdoc -c jsdoc.json -r ."
  },

When executing this script, we will return a folder called OUT in which we can see html, css files, among others, when opening the index.html we find a main page and in the upper right corner we see the two methods “diff” and “sum”, with a brief description that we provide more its parameters, as well as the possibility of seeing the complete code of the function,

Source: http://usejsdoc.org/

🤓 You can follow me on Twitter or find me on GitHub by visiting my website

Francisco Imanol Suarez on about.me