A documentation tool / generator is a programming tool which produces software documentation for the API (its modules, classes, functions, variables, etc.) or end-user guides, so that programmers or end-users can understand how the source code or application works. This is done by the tool parsing through specifically formatted comments in the source code written by the coder. The output resulted from documentation tools is usually HTML, which is used to generate a website neatly documenting the code.

The tool we will use to document the API in JavaScript has been chosen to be JSDocs, mainly due to its popularity. It is highly stable as it is among the oldest JavaScript documentation tools that is still actively updated. As such, it has also gained a widespread usage and adoption throughout the industry, including the leading software companies such as Google. Hence, learning to utilize JSDocs prepares all team members to code up to industry standards.

The rest of this page will layout a guide helping you get started with using JSDocs. If you would like to learn from their official website directly, visit : https://jsdoc.app

Open the terminal.
If you would like to install JSDocs locally to the project's package.json file (under devDependencies as it is a dev tool), head over to your project's directory and type :
npm install --save-dev jsdoc

If you'd like to install locally without updating package.json, then :
npm install git+https://github.com/jsdoc/jsdoc.git

If you want to install globally (note that package.json will not be updated) :
npm install -g jsdoc

The JSDoc CLI (Command Line Interface) is now available in your system.

/** * Calculates the sum of two numbers * * @param {number} a - The augend or the first number to be added * @param {number} b - The addend or the second number to be added * @returns {number} The sum of the two numbers */ function sum(a, b) { return a + b }

Above is the syntax for a basic function that calculates and returns the sum of two numbers.
The /** and */ indicates the start and end of the function's documentation, respectively.
* in between are used to indicate separate lines.
@ is the prefix for block tag symbols in JSDoc. @param tag describes parameters of a function and the word within the curly braces {} are their intended variable type. Next to the closing curly brace, we add the name of the parameter itself which is then to be described after the - separator.
@returns tag describes the returned value and its type similarly.

You can learn about all the other block tags and how to use them to document various features of your code.

Once your source code file is commented, you can use the JSDoc's CLI that we installed previously to generate an HTML website.\

To run the generator, open your terminal.
If JSDoc has been installed globally in your system, then simply head to your file's directory and type :
jsdoc myFilename.js

If JSDoc has been installed locally in your project directory, then you need to type:
./node_modules/.bin/jsdoc myFilename.js

This creates a folder named out in the current working directory. Within that folder, you will find the generated HTML pages.