Documentation

Every program describes how to accomplish some task in the language of mathematics and logic. While high level languages help us to express programming concepts easily and clearly, they are often not the best way to explain the abstract concepts involved. This is where programming documentation comes to the rescue. Documentation in the form of program comments interspersed in the source code are a means to explain in plain English the expected workings of a program and the high level concepts involved. They are a way to include information that is not obvious or clear in the programming statements themselves.

In this site we will use a standard block of comments at the beginning of each file to explain the purpose of the program in the file. We will include the program author, the date that the program was written and any updates that were made. This last use of comments to document the update history is one that should only be used for programs that are not under source code control. For complex multi-file programs a [[source code control system]] will be a necessity and will perform the task of managing the update history of files.

Basic comments take two forms: single-line and multiple-line. Single-line comments begin with a double slash (//) and continue to the end of the current line. They can start at the beginning of the line or anywhere in the middle of a line. Multi-line comments may begin anywhere using the comment start symbol (/*) and continue until the comment end symbol (*/). All characters in the comment are ignored and not considered to be executable program content.

The following are examples of comments.

// This is a single line comment

/* This is an example
   of a multi-line comment */

Each program file, class or function/method should have a comment preceding it that describes the purpose and typical usage of the item being documented. Comments should document the high-level behavior and not get involved in the specifics of the current implementation. Implementation details can change but the interface described by the comment should rarely change. It also helps to know how the program, class or function/method is intended to perform when the code itself is found to have a bug. The following is an example of what a program file comment might look like.

/*********************************************************************
 * This program computes ...
 *
 * Copyright © 2023 Richard Lesh.  All rights reserved.
 ********************************************************************/

Modern JavaScript Documentation

Modern JavaScript documentation has two layers:

Human-facing guides: README, tutorials, architecture notes, examples
API/reference docs: generated from source using JSDoc-style comments

What Should Be Documented

Modern JavaScript documentation should describe:

the purpose of a function, class, object, module, or constant
object lifecycle expectations
preconditions and postconditions
error behavior
asynchronous behavior when relevant
performance or complexity when relevant
examples of use

This aligns better with how modern JavaScript libraries are read and maintained. JavaScript commonly uses a documentation syntax called JSDoc. JSDoc reads specially formatted comments in JavaScript source code and can generate HTML API documentation automatically.

JSDoc Comments

JSDoc uses documentation comment blocks such as /** ... */. It supports summary and detailed descriptions, plus tags like @param, @returns, @throws, @example, and @typedef.

For example, a JSDoc comment for a function might look like this:

/**
 * Computes the area of a circle.
 *
 * Uses the standard formula pi * r^2.
 *
 * @param {number} radius - Radius of the circle in meters; must be non-negative.
 * @returns {number} Area in square meters.
 * @throws {RangeError} If radius is negative.
 */
function circleArea(radius) {
    if (radius < 0) {
        throw new RangeError("radius must be non-negative");
    }
    return Math.PI * radius * radius;
}

This is a typical JSDoc documentation block. The comment begins with /**. Unlike normal comments (// or /* */), this style signals to documentation tools that the text inside should be parsed and included in generated API documentation.

The comment is placed immediately before the function declaration, which tells JSDoc that the documentation applies to that function.

The first sentence provides a short summary of the function.

Most documentation systems display the summary description in:

function lists
summary tables
quick navigation views

The summary should explain what the function does, not how it works internally.

After the summary line, you can include additional explanatory text.

This section may describe:

the algorithm used
important assumptions
behavior that may not be obvious

JSDoc treats this as the detailed description of the function.

The @param tag documents each formal parameter of the function.

Good parameter documentation usually explains:

the meaning of the parameter
valid value ranges
units of measurement (if relevant)
any constraints or requirements

Each function parameter should normally have its own @param entry.

The @returns tag explains what value the function returns.

It should describe:

what the returned value represents
the units of the result if applicable
any special values that might be returned

Even if the return type is obvious from the code, describing the meaning of the result is helpful for readers.

The @throws tag documents exceptions that the function may throw.

It should include:

the exception type
the conditions under which it occurs

This helps programmers understand the error conditions that must be handled when calling the function.

Structured comments like this serve several purposes:

Readable source code documentation
Automatically generated API reference manuals
Improved IDE tooltips and code navigation
Clear documentation of interface contracts

Tools such as JSDoc can scan these comments and generate HTML documentation directly from the source code.

Classes, enumerations, objects, and type definitions can also have JSDoc comments placed before them. For example:

Class Example

/**
 * Represents a bank account with a running balance.
 *
 * Instances of this class are not thread-safe.
 */
class Account {
    #balance = 0;

    /**
     * Deposits money into the account.
     *
     * @param {number} amount - Amount to deposit; must be positive.
     */
    deposit(amount) {
        this.#balance += amount;
    }

    /**
     * Returns the current balance.
     *
     * @returns {number} Current balance in dollars.
     */
    getBalance() {
        return this.#balance;
    }
}

Enumeration-Style Object Example

/**
 * States a task can be in during execution.
 * @readonly
 * @enum {string}
 */
const TaskState = {
    PENDING: "pending",
    RUNNING: "running",
    COMPLETE: "complete",
    FAILED: "failed"
};

Generic-Like Type Example with Templates

/**
 * Returns the larger of two values.
 *
 * @template T
 * @param {T} a - First value.
 * @param {T} b - Second value.
 * @returns {T} The larger of a and b.
 */
function maxValue(a, b) {
    return a >= b ? a : b;
}

JSDoc uses the @template tag to document generic type parameters used by a function or class.

JSDoc can also document modules, callback types, and object shapes.

Module Example

/**
 * Utility functions for common mathematical operations.
 * @module mathUtils
 */

Object Type Example

/**
 * @typedef {Object} Point
 * @property {number} x - The x-coordinate.
 * @property {number} y - The y-coordinate.
 */

Callback Example

/**
 * Called when processing is complete.
 *
 * @callback CompletionHandler
 * @param {boolean} success - True if the operation succeeded.
 */

Modern docs are much easier to learn from when each API item includes a short usage example.

/**
 * Converts a string to uppercase.
 *
 * @param {string} text - Input text.
 * @returns {string} Uppercase copy of the input text.
 * @example
 * const s = toUpper("Hello");
 * // s === "HELLO"
 */
function toUpper(text) {
    return text.toUpperCase();
}

In JSDoc, the @example tag is used to show example code in generated documentation.

It helps readers see how a function, class, or object is intended to be used.

The example text is typically rendered in a fixed-width or preformatted style by documentation generators.

This makes it safer and clearer for showing program code in documentation.

Generating Documentation with JSDoc

Once your JavaScript code contains JSDoc-style comments, you can automatically generate a browsable documentation website.

Install JSDoc

JSDoc is commonly installed using Node.js and npm.

Linux and
Raspberry Pi

$ sudo apt install nodejs npm $ npm install -g jsdoc

macOS

% brew install node % npm install -g jsdoc

Windows

Node.js and npm can be installed using the installer at https://nodejs.org. Then you can install the jsdoc package.

> npm install -g jsdoc

Run JSDoc

Generate documentation by pointing JSDoc at one or more source files:

Linux and
Raspberry Pi

$ jsdoc src/*.js -d doc

macOS

% jsdoc src/*.js -d doc

Windows

> jsdoc src\*.js -d doc

The -d option tells JSDoc where to place the generated HTML documentation.

Generate Documentation for Larger Projects

In larger projects, it is more common to document an entire source directory. For example:

$ jsdoc src -r -d doc

This tells JSDoc to:

scan the src directory
recursively process files because of the -r option
write output into the doc directory

View the Generated Documentation

The generated documentation will appear in the output directory. Open the index.html file in a web browser to browse your project’s API documentation.

References

[[JavaScript Language Reference]], Mozilla Developer Network
[[Mozilla Developer Network]]
Download [[node.js]]
[[w3schools.com]]