Inline Documentation

Overview

Document code assuming docs will be generated from it.

Core principle: Future developers (including you) will read this code. Help them.

Announce at use: "I'm adding complete inline documentation for this code."

What to Document

Always Document

Skip Documentation For

TypeScript/JavaScript (JSDoc)

Function Documentation

/**
 * Calculates the total price including tax and discounts.
 *
 * @description Applies discounts before tax calculation.
 * Discounts are applied in order of magnitude (largest first).
 *
 * @param items - Line items to calculate
 * @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
 * @param discounts - Optional discount codes to apply
 * @returns Total price after discounts and tax
 *
 * @throws {ValidationError} If taxRate is negative
 * @throws {InvalidDiscountError} If discount code is invalid
 *
 * @example
 * ```typescript
 * const total = calculateTotal(
 *   [{ price: 100 }, { price: 50 }],
 *   0.08,
 *   ['SAVE10']
 * );
 * // Returns: 145.80 (150 - 10% discount = 135, + 8% tax)
 * ```
 */
function calculateTotal(
  items: LineItem[],
  taxRate: number,
  discounts?: string[]
): number {
  // Implementation
}

Class Documentation

/**
 * Manages user authentication and session lifecycle.
 *
 * @description Handles login, logout, session refresh, and
 * multi-device session management. Uses JWT for stateless
 * authentication with Redis for session invalidation tracking.
 *
 * @example
 * ```typescript
 * const auth = new AuthService(config);
 * const session = await auth.login(credentials);
 * await auth.logout(session.id);
 * ```
 */
class AuthService {
  /**
   * Creates an AuthService instance.
   *
   * @param config - Authentication configuration
   * @param config.jwtSecret - Secret for signing JWTs
   * @param config.sessionTtl - Session time-to-live in seconds
   */
  constructor(private config: AuthConfig) { }

  /**
   * Authenticates a user and creates a session.
   *
   * @param credentials - User credentials
   * @returns Session object with tokens
   * @throws {InvalidCredentialsError} If authentication fails
   */
  async login(credentials: Credentials): Promise<Session> { }
}

Interface Documentation

/**
 * Configuration for the caching layer.
 *
 * @description Controls cache behavior including TTL,
 * invalidation strategy, and storage backend selection.
 */
interface CacheConfig {
  /** Time-to-live in seconds. Default: 3600 */
  ttl: number;

  /** Maximum items to cache. Default: 1000 */
  maxSize: number;

  /**
   * Storage backend to use.
   * - 'memory': In-process LRU cache
   * - 'redis': Distributed Redis cache
   */
  backend: 'memory' | 'redis';

  /** Redis connection string (required if backend is 'redis') */
  redisUrl?: string;
}

Python (Docstrings)

Function Documentation

def calculate_total(
    items: list[LineItem],
    tax_rate: float,
    discounts: list[str] | None = None
) -> float:
    """Calculate the total price including tax and discounts.

    Applies discounts before tax calculation. Discounts are applied
    in order of magnitude (largest first).

    Args:
        items: Line items to calculate.
        tax_rate: Tax rate as decimal (e.g., 0.08 for 8%).
        discounts: Optional discount codes to apply.

    Returns:
        Total price after discounts and tax.

    Raises:
        ValidationError: If tax_rate is negative.
        InvalidDiscountError: If discount code is invalid.

    Example:
        >>> total = calculate_total(
        ...     [LineItem(price=100), LineItem(price=50)],
        ...     0.08,
        ...     ['SAVE10']
        ... )
        >>> total
        145.80  # 150 - 10% = 135, + 8% tax
    """
    pass

Class Documentation

class AuthService:
    """Manages user authentication and session lifecycle.

    Handles login, logout, session refresh, and multi-device
    session management. Uses JWT for stateless authentication
    with Redis for session invalidation tracking.

    Attributes:
        config: Authentication configuration.
        redis: Redis client for session tracking.

    Example:
        >>> auth = AuthService(config)
        >>> session = await auth.login(credentials)
        >>> await auth.logout(session.id)
    """

    def __init__(self, config: AuthConfig) -> None:

...