How to Document JavaScript Code

JSDoc Basics

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);
  }
}

TypeScript-Style Types in JSDoc

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();
}

Documenting React Components

/**
 * 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>
  );
}

Documentation Generation Tools

Best Practices

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

Generate Types from JSDoc

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.