Guide to Writing Code Using the JSDoc Standard

Introduction

JSDoc is a widely used standard for documenting JavaScript code. It provides a way to add inline comments that describe the purpose, parameters, return values, and behavior of your code. These comments can be parsed to generate HTML documentation, making it easier to maintain and understand your code.

Basic JSDoc Syntax

JSDoc comments are written inside /** ... */ blocks and should be placed directly above the function, class, or variable you're documenting.

/**
 * A simple function that adds two numbers.
 * @param {number} a - The first number to add.
 * @param {number} b - The second number to add.
 * @returns {number} The sum of the two numbers.
 */
function add(a, b) {
  return a + b;
}
    

Documenting Functions

When documenting functions, you generally need to describe the following:

• Function Purpose: A short description of what the function does.
• Parameters (@param): Each parameter should be described, including its data type and role.
• Return Value (@returns): The type and meaning of the value returned by the function.

/**
 * Multiplies two numbers.
 * @param {number} num1 - The first number.
 * @param {number} num2 - The second number.
 * @returns {number} The product of num1 and num2.
 */
function multiply(num1, num2) {
  return num1 * num2;
}
    

Documenting Objects and Properties

You can document object types and their properties using the @typedef tag. This is helpful when working with complex data structures.

/**
 * A point in 2D space.
 * @typedef {Object} Point
 * @property {number} x - The X coordinate.
 * @property {number} y - The Y coordinate.
 */

/**
 * Calculates the distance between two points.
 * @param {Point} point1 - The first point.
 * @param {Point} point2 - The second point.
 * @returns {number} The distance between the two points.
 */
function calculateDistance(point1, point2) {
  const dx = point1.x - point2.x;
  const dy = point1.y - point2.y;
  return Math.sqrt(dx * dx + dy * dy);
}
    

Documenting Classes

When documenting classes, you can use the @class tag to describe the class and the @constructor tag to describe the constructor function. Document the methods just like functions.

/**
 * Represents a circle.
 * @class
 */
class Circle {
  /**
   * Creates a new Circle.
   * @constructor
   * @param {number} radius - The radius of the circle.
   */
  constructor(radius) {
    this.radius = radius;
  }

  /**
   * Calculates the area of the circle.
   * @returns {number} The area of the circle.
   */
  getArea() {
    return Math.PI * this.radius ** 2;
  }
}
    

Documenting Variables

To document a variable, use the @type tag, which specifies the data type of the variable.

/**
 * The radius of a circle.
 * @type {number}
 */
let radius = 5;
    

Specifying Data Types

JSDoc uses various data type annotations for clarity, such as:

• Primitive types: string, number, boolean, etc.
• Object types: {Object}, {Array}, {Function}, etc.
• Custom types: Use @typedef for custom object types.

/**
 * Represents a user profile.
 * @typedef {Object} UserProfile
 * @property {string} username - The user's name.
 * @property {number} [age] - The user's age (optional).
 * @property {boolean} isActive - Whether the user is active.
 */

Documenting Asynchronous Functions

To document functions that return promises or are asynchronous, use @async and @returns {Promise<type>}.

/**
 * Fetches user data from the server.
 * @async
 * @param {number} userId - The ID of the user.
 * @returns {Promise