JSDoc is a standard for documenting JavaScript code, particularly for adding docstrings to functions. By using JSDoc, you can provide clear and structured documentation for your code, including information about function parameters, return values, and more. This might help with intellisense suggestions and validation too. This page will guide you through the basics of JSDoc and its usage.

IDEs like VS Code support synax highlighting to help write the docstrings.

Resources

CLI

Generate HTML documentation using the NPM package.

$ jsdoc book.js

Syntax

Common JSDoc Tags

  • @param: Documents a function parameter.
  • @returns: Documents the return value of a function.
  • @throws: Documents the errors that a function may throw.
  • @example: Provides an example usage of a function.

Overview

Consider the following example that demonstrates the usage of JSDoc in a JavaScript function:

/**
 * Generate a book description.
 *
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 *
 * @returns {string} Description of the book.
 * @throws An error if values are not set.
 */
function Book(title, author) {
  if (!title || !author) {
    throw new Error('title and author must be set');
  }
  
  return `${title} by ${author}`;
}

Parameter name only

The type is omitted. You could also use {*} for any type.

/**
 * @param author
 */
function sayHello(author) {
}

Name and type

/**
 * @param {string} author
 */
function sayHello(author) {
}

Name, type, and description

/**
 * @param {string} author Somebody's name.
 */
function sayHello(author) {
}

Or with a hyphen.

/**
 * @param {string} author - Somebody's name.
 */
function sayHello(author) {
}

Optional

Use square brackets.

/**
 * @param {string} [author] - Somebody's name.
 * // OR
 * @param {?string} author - Somebody's name.
 */
function sayHello(author) {
}

Types

Primitives

Note use of lowercase.

{string}
{number}
{boolean}

{(number|boolean)}

Hashes

Aka key-value pair objects.

Note use of titlecase.

{Object}

e.g.

/**
 * @param {Object} employee - The employees who is responsible for the project.
 */

You can break out the attributes using the name of the key.

/**
 * @param {Object} employee - The employees who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */

Array

Array of strings.

{string[]}

// Or, less common form:
{Array.<string>}

An array of MyClass instances.

{MyClass[]}

// Or, less common:
{Array.<MyClass>}

An array of hashes (key-value pair objects), with keys described for the items.

/**
 * Assign the project to a list of employees.
 *
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */

Nullable

Value may be null, undefined, or set.

{?number}

Required

Value is “non-nullable” i.e. must be set and never null or undefined.

{!number}