JSDoc Annotations

                /** @param {Type} name @returns {Type} */
              

Purpose

JSDoc comments annotate a function’s parameters, return value, and other contracts in plain JavaScript comments — most modern editors read them directly for autocomplete, inline hints, and type-mismatch warnings, with no compilation step needed.

Syntax

/**
 * Calculate the total price for a cart, including tax.
 * @param {Array<{ price: number, quantity: number }>} items
 * @param {number} taxRate - A decimal, e.g. 0.08 for 8%.
 * @returns {number} The total price, tax included.
 */
function calculateTotal(items, taxRate) {
  const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  return subtotal * (1 + taxRate);
}

Behavior notes

• {Type} syntax supports primitives (string, number, boolean), arrays (Array<T> or T[]), unions (string | number), and inline object shapes ({ id: number, name: string }).
• A // @ts-check comment at the top of a .js file turns on TypeScript’s type checker against a file’s JSDoc annotations, without converting the file to .ts — a lightweight way to get real type-checking in a plain JavaScript project.
• JSDoc types provide editor/tooling information only — they add no runtime enforcement at all. See runtime validation.

Common mistakes

• Letting JSDoc annotations drift out of sync with the actual function signature over time, since nothing enforces they stay accurate without @ts-check (or full TypeScript) actively verifying them.
• Assuming a JSDoc-documented parameter type is checked at runtime — it isn’t, unless separately validated in the function body.

Runtime notes

A tooling/editor convention read by TypeScript’s language service and most modern editors — has no effect on runtime behavior in any JavaScript environment.