Writing JSDoc comments for JavaScript functions

JSDoc for JavaScript Functions

JSDoc comments generate documentation and power IDE autocomplete. Every public function in a library or SDK should have a JSDoc comment — it's the contract between your function and its callers.

Complete JSDoc Example

/**
 * Creates a new user in the database and sends a verification email.
 *
 * @param {string} email - Valid email address for the new user
 * @param {string} name - Display name, 2–100 characters
 * @param {'admin' | 'editor' | 'viewer'} [role='viewer'] - User role
 * @returns {Promise} The created user object with generated ID
 * @throws {ValidationError} If email format is invalid or name is out of range
 * @throws {DuplicateError} If a user with this email already exists
 *
 * @example
 * const user = await createUser('alice@example.com', 'Alice Chen', 'editor');
 * console.log(user.id); // 'usr_01HQ...'
 */
async function createUser(email, name, role = 'viewer') {

Key Tags

• @param {type} name - description — document every parameter with type and constraint
• @returns {type} — document what's returned, including Promise resolution
• @throws {ErrorType} — document every exception the caller must handle
• @example — include one minimal working example

JSDoc in TypeScript

In TypeScript, use JSDoc for @throws and @example since types are in the signature. Never duplicate type information already in TypeScript annotations.