How to Document JavaScript Code

JSDoc is the standard way to document JavaScript. Modern IDEs like VS Code parse JSDoc to provide IntelliSense, type checking, and hover documentation.

Function Documentation

/**
 * Calculate the total price with tax.
 *
 * @param {number} price - Base price before tax
 * @param {number} [taxRate=0.1] - Tax rate as decimal
 * @returns {number} Total price including tax
 * @throws {Error} If price is negative
 *
 * @example
 * calculateTotal(100, 0.08) // Returns 108
 */
function calculateTotal(price, taxRate = 0.1) {
  if (price < 0) throw new Error("Price cannot be negative");
  return price * (1 + taxRate);
}

Class Documentation

/**
 * Shopping cart for managing items.
 *
 * @class
 * @example
 * const cart = new ShoppingCart();
 * cart.addItem({ name: "Widget", price: 9.99 });
 */
class ShoppingCart {
  /**
   * Create a new shopping cart.
   * @param {Object} [options] - Cart configuration
   * @param {string} [options.currency="USD"] - Currency code
   */
  constructor(options = {}) {
    /** @type {Array<Object>} */
    this.items = [];
    /** @type {string} */
    this.currency = options.currency || "USD";
  }

  /**
   * Add an item to the cart.
   * @param {Object} item - Item to add
   * @param {string} item.name - Item name
   * @param {number} item.price - Item price
   */
  addItem(item) {
    this.items.push(item);
  }
}

You can use TypeScript syntax in JSDoc for complex types:

/**
 * @typedef {Object} User
 * @property {number} id - Unique identifier
 * @property {string} name - Display name
 * @property {string} email - Email address
 * @property {"admin" | "user" | "guest"} role - User role
 */

/**
 * Fetch user from API.
 * @param {number} userId - User ID to fetch
 * @returns {Promise<User | null>} User object or null
 */
async function getUser(userId) {
  const response = await fetch(`/api/users/${userId}`);
  return response.json();
}

/**
 * Button component with loading state.
 *
 * @param {Object} props - Component props
 * @param {React.ReactNode} props.children - Button content
 * @param {boolean} [props.loading=false] - Show loading spinner
 * @param {"primary" | "secondary"} [props.variant="primary"] - Button style
 * @param {() => void} [props.onClick] - Click handler
 * @returns {JSX.Element} Rendered button
 *
 * @example
 * <Button variant="primary" onClick={handleSubmit}>
 *   Submit
 * </Button>
 */
function Button({ children, loading = false, variant = "primary", onClick }) {
  return (
    <button className={variant} onClick={onClick} disabled={loading}>
      {loading ? <Spinner /> : children}
    </button>
  );
}

1. Document exports - Focus on public APIs that others will use
2. Add examples - Show usage, not just parameter lists
3. Use @typedef for complex types - Define reusable type definitions
4. Enable VS Code JSDoc checking - Add "checkJs": true to jsconfig.json
5. Consider TypeScript - Types serve as living documentation

TypeScript can generate .d.ts files from JSDoc comments:

// tsconfig.json
{
  "compilerOptions": {
    "allowJs": true,
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "types"
  },
  "include": ["src/**/*.js"]
}

Run tsc to generate type definitions that npm packages can include.

• JSDoc official documentation
• TypeScript handbook: JSDoc supported types
• ESLint JSDoc guidance