basics
Documenting a Function
/**
* Calculates the total price with tax.
*
@param {number} price - Base price
@param {number} taxRate - Tax as decimal
@returns {number} Total including tax
*/
function calcTotal(price, taxRate) {
return price * (1 + taxRate);
}
types
Type Syntax
@param {string} // primitive
@param {number}
@param {boolean}
@param {Object} // object
@param {string[]} // array of strings
@param {Array.<number>} // array (alt)
@param {string|number} // union
@param {*} // any type
@param {?string} // nullable
@param {!string} // non-nullable
@returns {Promise<User>} // promise
parameters
Optional & Default Params
/**
@param {string} name required
@param {number} [age] optional
@param {boolean} [active=true] with default
*/
function createUser(name, age, active = true) {}
// Destructured object param:
/**
@param {Object} opts
@param {string} opts.name
@param {number} opts.age
*/
function createUser({ name, age }) {}
variables
Annotating Variables
/** @type {string} */
let username = 'alice';
/** @type {number[]} */
const scores = [];
/** @type {HTMLCanvasElement} */
const canvas = document.querySelector('canvas');
/** @type {Map<string, number>} */
const lookup = new Map();
custom types
@typedef — Define a Type
/**
@typedef {Object} User
@property {number} id
@property {string} name
@property {string} [email] optional
*/
// Now use it anywhere:
/**
@param {User} user
@returns {string}
*/
function greet(user) {
return `Hello, ${user.name}`;
}
callbacks
@callback — Function Types
/**
@callback Predicate
@param {number} value
@returns {boolean}
*/
/**
@param {number[]} arr
@param {Predicate} fn
*/
function filter(arr, fn) {
return arr.filter(fn);
}
classes
Documenting Classes
/**
* Represents a 2D point.
@class
*/
class Point {
/**
@param {number} x
@param {number} y
*/
constructor(x, y) {
/** @type {number} */
this.x = x;
/** @type {number} */
this.y = y;
}
}
async
Async Functions
/**
* Fetches a user from the API.
@async
@param {number} id
@returns {Promise<User>}
@throws {Error} If not found
*/
async function fetchUser(id) {
const res = await fetch(`/users/${id}`);
if (!res.ok) throw new Error('Not found');
return res.json();
}
enums
Enum-like Constants
/**
* Direction options.
@enum {string}
*/
const Direction = {
UP: 'up',
DOWN: 'down',
LEFT: 'left',
RIGHT: 'right',
};
/**
@param {Direction} dir
*/
function move(dir) { /* ... */ }
modifiers
Access & State Tags
/** @private */ // not part of public API
/** @protected */ // accessible to subclasses
/** @public */ // explicitly public
/** @readonly */ // should not be reassigned
/** @static */ // static member
/** @abstract */ // must be implemented
/** @override */ // overrides parent method
/**
@deprecated Use newFn() instead.
*/
generics
Generic / Template Types
/**
@template T
@param {T[]} arr
@param {function(T): boolean} fn
@returns {T[]}
*/
function filter(arr, fn) {
return arr.filter(fn);
}
// Multiple type params:
/** @template K, V */
modules
Module & File Tags
/**
* Utilities for date formatting.
@module dateUtils
*/
/**
@file Entry point for the app.
@author Alice <alice@example.com>
@version 1.0.0
@license MIT
@since 2024-01-01
*/
references
Links, Examples & See Also
/**
* Parses a date string.
* See {@link https://mdn.io/Date}
* See also {@link formatDate}
@see formatDate
@example
// Basic usage:
parseDate('2024-01-01'); // → Date
@example <caption>With timezone</caption>
parseDate('2024-01-01', 'UTC');
*/
ts-check
TypeScript in Plain JS
// @ts-check ← add at top of file
// enables TS type checking via JSDoc
/** @type {import('./types').Config} */
const config = { port: 3000 };
// Import types from .d.ts or TS files:
/** @typedef {import('express').Request} Req */
// Cast a type:
const el = /** @type {HTMLInputElement} */
(document.getElementById('input'));
quick reference
All Common Tags
| @param | Document a function parameter |
| @returns | Document the return value |
| @type | Annotate a variable's type |
| @typedef | Define a reusable custom type |
| @callback | Define a function signature type |
| @template | Generic / type parameter |
| @enum | Document an enum-like object |
| @property / @prop | Document an object property (inside @typedef) |
| @throws / @exception | Document errors the function may throw |
| @async | Mark a function as asynchronous |
| @deprecated | Mark as deprecated with optional message |
| @private / @protected / @public | Access level modifiers |
| @readonly | Mark a value as read-only |
| @static | Mark a class member as static |
| @abstract | Mark a method as abstract |
| @override | Mark a method as overriding parent |
| @class / @constructor | Mark a function as a constructor |
| @extends / @augments | Document class inheritance |
| @implements | Document interface implementation |
| @example | Add a usage example |
| @see | Link to related item or URL |
| {@link} | Inline hyperlink in description text |
| @module | Mark a file as a module |
| @file / @fileoverview | Describe the file |
| @author | Document the author |
| @version | Document the version |
| @since | When the item was added |
| @license | License type |
| @todo | Note something to fix or add |
| @ignore | Exclude from generated docs |