JSDoc Cheatsheet

Table of Contents

JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor. You add documentation comments directly to your source code, right alongside the code itself. The JSDoc tool will scan your source code and generate an HTML documentation website for you.

Functions

/**
 * This is a function.
 *
 * @param {string} n - A string param
 * @return {string} A good string
 *
 * @example
 *
 *     foo('hello')
 */

function foo(n) {
    return n
}

See: http://usejsdoc.org/index.html

Types

TypeDescription
@param {string=} nOptional
@param {string} [n]Optional
@param {(string|number)} nMultiple types
@param {*} nAny type
@param {...string} nRepeatable arguments
@param {string} [n="hi"]Optional with default
@param {string[]} nArray of strings
@return {Promise<string[]>} nPromise fulfilled by array of strings

See: http://usejsdoc.org/tags-type.html

Variables

/**
 * @type {number}
 */
var FOO = 1

/**
 * @const {number}
 */
const FOO = 1

Typedef

/**
 * A song
 * @typedef {Object} Song
 * @property {string} title - The title
 * @property {string} artist - The artist
 * @property {number} year - The year
 */

/**
 * Plays a song
 * @param {Song} song - The {@link Song} to be played
 */

function play(song) {}

See: http://usejsdoc.org/tags-typedef.html

Typedef Shorthand

/**
 * A song
 * @typedef {{title: string, artist: string, year: number}} Song
 */

/**
 * Plays a song
 * @param {Song} song - The {@link Song} to be played
 */

function play(song) {}

See: http://usejsdoc.org/tags-typedef.html

Importing types

/**
 * @typedef {import('./Foo').default} Bar
 */

/**
 * @param {Bar} x
 */

function test(x) {}

This syntax is TypeScript-specific.

Other keywords

/**
 * @throws {FooException}
 * @private
 * @deprecated
 * @see
 *
 * @function
 * @class
 */

Renaming

/*
 * @alias Foo.bar
 * @name Foo.bar
 */

Prefer alias over name. See: http://usejsdoc.org/tags-alias.html

Related