Comprehensive JSDoc Cheatsheet

Introduction

JSDoc is a markup language used to annotate JavaScript source code files. It provides a way to document the code and its API. This cheatsheet covers the main JSDoc tags and their usage.

Basic Structure

A basic JSDoc comment looks like this:

/**
 * This is a JSDoc comment
 */

Function Documentation

/**
 * Calculates the sum of two numbers
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {number} The sum of a and b
 */
function sum(a, b) {
    return a + b;
}

Class Documentation

/**
 * Represents a book
 * @class
 */
class Book {
    /**
     * Create a book
     * @param {string} title - The title of the book
     * @param {string} author - The author of the book
     */
    constructor(title, author) {
        this.title = title;
        this.author = author;
    }

    /**
     * Get the book's title
     * @returns {string} The title of the book
     */
    getTitle() {
        return this.title;
    }
}

Common Tags

@param

Used to describe a function parameter.

/**
 * @param {string} name - The name of the person
 * @param {number} [age] - The age of the person (optional)
 * @param {boolean} [isStudent=false] - Whether the person is a student (default: false)
 */
function describePerson(name, age, isStudent) {
    // Function body
}

@returns

Describes the return value of a function.

/**
 * @returns {Promise<string>} A promise that resolves with a greeting
 */
async function getGreeting() {
    return "Hello, World!";
}

@throws

Documents exceptions that might be thrown.

/**
 * @throws {Error} If the input is not a number
 */
function squareRoot(x) {
    if (typeof x !== 'number') {
        throw new Error('Input must be a number');
    }
    return Math.sqrt(x);
}

@type

Specifies the type of a variable or property.

/** @type {string} */
let name = "John Doe";

/** @type {number[]} */
let scores = [98, 85, 91];

@typedef

Defines a custom type.

/**
 * @typedef {Object} Person
 * @property {string} name - The person's name
 * @property {number} age - The person's age
 */

/** @type {Person} */
let person = { name: "John", age: 30 };

@callback

Documents a callback function.

/**
 * @callback CompareCallback
 * @param {*} a - The first element to compare
 * @param {*} b - The second element to compare
 * @returns {number} A negative number if a < b, positive if a > b, zero if equal
 */

/**
 * Sorts an array using a compare function
 * @param {Array} arr - The array to sort
 * @param {CompareCallback} compareFunc - The compare function
 * @returns {Array} The sorted array
 */
function customSort(arr, compareFunc) {
    return arr.sort(compareFunc);
}

@async

Indicates that a function is asynchronous.

/**
 * @async
 * @returns {Promise<string>} A promise that resolves with data
 */
async function fetchData() {
    // Function body
}

@deprecated

Marks a function or method as deprecated.

/**
 * @deprecated since version 2.0.0, use newFunction() instead
 */
function oldFunction() {
    // Function body
}

@private, @protected, @public

Specifies the visibility of a member.

class MyClass {
    /**
     * @private
     */
    #privateMethod() {
        // Method body
    }

    /**
     * @protected
     */
    _protectedMethod() {
        // Method body
    }

    /**
     * @public
     */
    publicMethod() {
        // Method body
    }
}

@example

Provides an example of how to use a function or class.

/**
 * Adds two numbers
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {number} The sum of a and b
 * @example
 * // returns 5
 * add(2, 3)
 */
function add(a, b) {
    return a + b;
}

@see

Refers to another symbol or resource.

/**
 * @see {@link otherFunction} for related functionality
 */
function someFunction() {
    // Function body
}

@todo

Indicates tasks that need to be completed.

/**
 * @todo Implement error handling
 * @todo Add support for negative numbers
 */
function calculateSquareRoot(x) {
    return Math.sqrt(x);
}

@since

Indicates when a function or feature was added.

/**
 * @since 1.5.0
 */
function newFeature() {
    // Function body
}

@ignore

Tells JSDoc to ignore the following code when generating documentation.

/**
 * @ignore
 */
function internalHelper() {
    // Function body
}