Documentation Comments in JSDoc

In JSDoc we need to include documentation comments in the code through which JSDoc will generate an HTML documentation website. Let’s see how to create documentation comments for different types of code.

String, Numbers & Arrays:

Javascript

/**
 * Site Name
 * @type {string}
 */
const siteName = "GeeksForGeeks";

/**
 * Number
 * @type {number}
 */
const number = 1000;

/**
 * Array
 * @type {Array<number>}
 */
const myArray = [10, 20, 30];

Here we have generated simple JSDoc comments with the description of variables and their data type which is denoted with the help of the @type tag.

Objects:

Javascript

/**
 * Site object
 * @type {{id: number, name: string, rank: number|string}}
 */
const site = {
  id: 1,
  name: "gfg",
  rank: 1,
};

In the above comment, we have specified the type of all properties of an object.

Function/Methods:

Javascript

/**
 * Calculate age
 * @param {number} current Current year
 * @param {number} yearOfBirth Year of Birth
 * @returns {string} your calculated age
 */
const calcAge = (current, yearOfBirth) => {
  return `${current - yearOfBirth}`;
};

Here, the @param tag is used for documenting the different parameters of the function, whereas the @returns tag documents the return value of the function

Class:

Javascript

/**
 * Class to create new owner
 */
class Owner {
  /**
   * Owner details
   * @param {Object} ownerDetail
   */
  constructor(ownerDetail) {
    /**
     * @property {string} name Owner name
     */
    this.name = ownerDetail.name;

    /**
     * @property {number} age Owner's age
     */
    this.age = ownerDetail.age;
  }

  /**
   * @property {Function} printOwner Prints Owner's details
   * @returns {void}
   */
  printOwner() {
    console.log(`Owner's name is ${this.name}
            and his age is ${this.age}`);
  }
}

Explanation: 

• Before the declaration of the class, we have JSDoc comment to describe the class
• For Constructor, JSDoc comment similar to Function is used
• Inside the Constructor, to document variables, the @property tag is used

Linking instance of the class to its class

As we have created a class named “Owner”, so let’s create an instance of that class and link it to the class with the help of the @link tag

Javascript

/**
 * Link to Owner Class
 * See {@link Owner}
 */
const gfg = new Owner({
  name: "GeeksForGeeks",
  age: 13,
});

Final index.js file: 

Javascript

// @ts-check

/**
 * Site Name
 * @type {string}
 */
const siteName = "GeeksForGeeks";

/**
 * Number
 * @type {number}
 */
const number = 1000;

/**
 * Array
 * @type {Array<number>}
 */
const myArray = [10, 20, 30];

/**
 * Site object
 * @type {{id: number, name: string, rank: number|string}}
 */
const site = {
  id: 1,
  name: "gfg",
  rank: 1,
};

/**
 * Calculate age
 * @param {number} current Current year
 * @param {number} yearOfBirth Year of Birth
 * @returns {string} your calculated age
 */
const calcAge = (current, yearOfBirth) => {
  return `${current - yearOfBirth}`;
};

/**
 * Class to create new owner
 */
class Owner {
  /**
   * Owner details
   * @param {Object} ownerDetail
   */
  constructor(ownerDetail) {
    /**
     * @property {string} name Owner name
     */
    this.name = ownerDetail.name;

    /**
     * @property {number} age Owner's age
     */
    this.age = ownerDetail.age;
  }

  /**
   * @property {Function} printOwner Prints Owner's details
   * @returns {void}
   */
  printOwner() {
    console.log(`Owner's name is ${this.name} and his age is ${this.age}`);
  }
}

/**
 * Link to Owner Class
 * See {@link Owner}
 */
const gfg = new Owner({
  name: "GeeksForGeeks",
  age: 13,
});

Output: Run the following jsdoc command:

npm run jsdoc

After executing the command, In the jsdoc folder, an index.html page would be created, open it in the browser to view the documentation site generated by jsdoc.

Documentation site Output:

Home page of Documentation site generated by JSDoc

Owner Class Documentation

Some common tags used in JSDoc comments:

• @author – To document the author of the code.
• @constant – To document constants.
• @default – Allows documenting the default value given to something.
• @function – This tag is used to describe the function or method.
• @global – Documents the global object.
• @implements – To document the implementation of an interface.
• @member – Documents the members of the function.
• @module – Used for documenting JavaScript module.
• @param – This tag is used to document parameters/arguments of the function.
• @returns – It is used to document the return value of the function.
• @type – To document the type of variables