How to Document JavaScript Code Using JSDoc

Proper codification archiving is captious for maintainability. Using JSDocs, you tin embed it correct wrong your codification truthful it’s ever astatine hand.

Proper codification archiving is an important yet often overlooked facet of package development. As a developer, you’ll beryllium utilized to penning clean, businesslike code, but you whitethorn beryllium little knowledgeable astatine penning bully documentation.

Good archiving is useful for anyone moving pinch your code, whether it’s different members of your team, aliases you, yourself, astatine a later date. It tin explicate why you’ve implemented thing a peculiar measurement aliases really to usage a peculiar usability aliases API.

For JavaScript developers, JSDoc is simply a bully measurement to commencement documenting your code.

What Is JSDoc?

Documenting codification tin beryllium analyzable and tedious. However, much group are recognizing nan benefits of a “docs arsenic code” approach, and galore languages person libraries that thief automate nan process. For simple, clear, and concise documentation. Just for illustration nan Go connection has GoDoc to automate archiving from code, truthful JavaScript has JSDoc.

JSDoc generates archiving by interpreting typical comments successful your JavaScript root code, processing these comments, and producing bespoke documentation. It past makes this archiving disposable successful an accessible HTML format.

This keeps nan archiving wrong nan code, truthful erstwhile you update your code, it's easy to update nan documentation.

Setting Up JSDoc

The creators of JSDoc person made it easy to get started and group up JSDoc successful your JavaScript project.

To instal JSDoc locally, run:

npm instal --save-dev jsdoc

This will instal nan room successful your task arsenic a dev dependency.

To usage JSDoc, you will usage typical syntax comments wrong your root code. You will constitute each your archiving comments wrong /** and */ markers. Inside these, you tin picture defined variables, functions, usability parameters, and a batch else.

For example:

 * Gets User by name.
 * @param {string} sanction - The sanction of nan User
 * @returns {string} User
 */

function getUser(name) {
  const User = name;
  return User;
}

The @param and @returns tags are 2 of nan galore typical keywords that JSDoc supports to explicate your code.

To make nan archiving for this code, tally npx jsdoc followed by nan way to your JavaScript file.

For example:

npx jsdoc src/main.js

This bid will make an out files successful your task root. Inside nan folder, you will find HTML files representing nan pages of your documentation.

You tin position nan archiving by setting up a section web server to big it, aliases simply by opening nan out/index.html record wrong a browser. Here’s an illustration of what a archiving page will look for illustration by default:

Configuring nan JSDoc Output

You tin create a configuration record to alteration JSDoc’s default behavior.

To do so, create a conf.js record and export a JavaScript module wrong this file.

For example:

module.exports = {
  source: {
    includePattern: ".+\\\\.js(doc|x)?$",
    excludePattern: ["node_modules"],
  },
  recurseDepth: 5,
  sourceType: "module",
  opts: {
    template: "path/to/template",
    destination: "./docs/",
    recurse: true,
  },
};

Inside nan configuration record are various JSDoc configuration options. The template action lets you usage a template to customize nan documentation’s appearance. JSDoc’s organization provides galore templates that you tin use. The package besides allows you to create your ain personalized templates.

To alteration nan location of nan generated documentation, group nan destination config action to a directory. The illustration supra specifies a docs files successful nan project’s root.

Use this bid to tally JSDoc pinch a configuration file:

jsdoc -c /path/to/conf.js

To make it easier to tally this command, adhd it arsenic a scripts introduction wrong your package.json file:

"scripts": {
    "dev": "nodemon app.js",
    "run-docs": "jsdoc -c /path/to/conf.js"
 },

You tin now run nan npm book command wrong a terminal.

An Example of Documentation Generated With JSDoc

Below is simply a elemental arithmetic room pinch add and subtract methods.

This is an illustration of well-documented JavaScript code:

 * A room for performing basal arithmetic operations.
 * @module arithmetic
 */
module.exports = {
    
     * Adds 2 numbers.
     * @param {number} a - The first number.
     * @param {number} b - The 2nd number.
     * @return {number} The sum of nan 2 numbers.
     * @throws {TypeError} If immoderate of nan arguments is not a number.
     *
     * @example
     * const arithmetic = require('arithmetic');
     * const sum = arithmetic.add(5, 10);
     * console.log(sum);
     */
    add: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('Both arguments must beryllium numbers.');
        }

        return a + b;
    },

    
     * Subtracts nan 2nd number from nan first number.
     * @param {number} a - The number to subtract from.
     * @param {number} b - The number to subtract.
     * @return {number} The consequence of nan subtraction.
     * @throws {TypeError} If immoderate of nan arguments is not a number.
     *
     * @example
     * const arithmetic = require('arithmetic');
     * const quality = arithmetic.subtract(10, 5);
     * console.log(difference);
     */
    subtract: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('Both arguments must beryllium numbers.');
        }

        return a - b;
    }

    
};

The JSDoc comments supply a clear and broad explanation of nan room and its methods, including:

• A explanation of nan room and its purpose.
• Each method’s parameters, including their type and a little description.
• The worth and type that each method returns.
• The errors that each method tin propulsion and nan conditions that origin it.
• An illustration of really to usage each method.

The comments besides see nan @module tag to bespeak that this record is simply a module and nan @example tag to supply a codification illustration for each method.

Documenting Developer Code nan Right Way

As you tin see, JSDoc is simply a very useful instrumentality to get you started documenting JavaScript code. With its easy integration, you tin make speedy and elaborate archiving arsenic you constitute your code. You tin besides support and update nan archiving correct successful your workspace.

However, arsenic useful arsenic JSDoc’s automation is, you should still adhere to definite guidelines truthful you tin create value documentation.