troykelly/inline-documentation

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

| Element | Documentation Required | |---------|----------------------| | Public functions/methods | Full JSDoc/docstring | | Public classes | Class-level documentation | | Public interfaces/types | Description of purpose | | Exported constants | What they control | | Complex logic | Why, not what | | Non-obvious decisions | Explain reasoning |

Skip Documentation For

| Element | Why | |---------|-----| | Private trivial helpers | Self-evident | | Single-line getters | Obvious from name | | Standard patterns | Well-known idioms | | Test files | Tests are documentation |

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:
        """Create an AuthService instance.

        Args:
            config: Authentication configuration including
                JWT secret and session TTL.
        """
        pass

Inline Comments

When to Use

// Complex algorithms
function dijkstra(graph: Graph, start: Node): Map<Node, number> {
  // Use priority queue for O(E log V) complexity
  // instead of linear search O(V²)
  const queue = new PriorityQueue<Node>();

  // Initialize all distances to infinity except start
  const distances = new Map<Node, number>();

  // ... implementation with strategic comments
}

Explain Why, Not What

// BAD: Explains what (obvious from code)
// Increment counter by 1
counter++;

// GOOD: Explains why (not obvious)
// Retry count starts at 1 because initial attempt doesn't count
counter++;

Link to Context

// Per RFC 7519, JWT expiry is in seconds since epoch
const exp = Math.floor(Date.now() / 1000) + ttlSeconds;

// See issue #234 for why we can't use the simpler approach
const result = complexWorkaround();

Mark Non-Obvious Behavior

// IMPORTANT: Order matters here - auth must run before rate limit
app.use(authMiddleware);
app.use(rateLimitMiddleware);

// WARNING: This modifies the input array in place
items.sort((a, b) => a.priority - b.priority);

Documentation Checklist

For each public element:

Functions/Methods

• [ ] Brief description (first line)
• [ ] Detailed description (if complex)
• [ ] All parameters documented
• [ ] Return value documented
• [ ] Exceptions documented
• [ ] Example provided (if non-obvious usage)

Classes

• [ ] Class purpose described
• [ ] Usage example provided
• [ ] All public methods documented
• [ ] Public properties documented

Interfaces/Types

• [ ] Purpose described
• [ ] Each property documented
• [ ] Valid values noted (for enums/unions)

Anti-Patterns

| Anti-Pattern | Correct Approach | |--------------|------------------| | No documentation | Document all public APIs | | Stale documentation | Update docs with code changes | | Obvious comments | Only document non-obvious | | Missing examples | Add examples for complex APIs | | Copy-paste docs | Write specific documentation |

Generating Documentation

TypeScript

# Using TypeDoc
npx typedoc src/index.ts --out docs

# Using TSDoc
npx @microsoft/api-extractor run

Python

# Using Sphinx
sphinx-apidoc -o docs/source src/
sphinx-build docs/source docs/build

# Using pdoc
pdoc --html src/ -o docs/

Integration

This skill is applied by:

• issue-driven-development - Step 7
• comprehensive-review - Documentation criterion

This skill ensures:

• Maintainable code
• Onboarding ease
• Generated documentation quality
• API discoverability