The Art of Documentation

Documentation is not a chore—it's a gift to your future self. Good docs reduce onboarding time, prevent bugs, and make code maintainable.

Philosophy

Bad documentation: Describes what code does line by line
Good documentation: Explains why it exists, how to use it, and what to expect

The best documentation answers:

1. What is this? (purpose)
2. How do I use it? (examples)
3. What should I know? (gotchas, edge cases)

---

Documentation Layers

Layer 1: Code as Documentation

The code itself should be readable. Names, structure, and flow should tell the story.

Layer 2: Inline Comments

Explain the "why" when code can't.

Layer 3: Doc Comments (JSDoc/TSDoc)

Describe interfaces, parameters, returns, and usage.

Layer 4: External Docs

READMEs, guides, API references for broader context.

---

What to Document

Always Document

• Public APIs: Anything others will call
• Complex logic: Algorithms, business rules
• Non-obvious decisions: Why this approach?
• Workarounds: Why the hack exists
• Edge cases: What breaks, what's unsupported

Skip Documentation For

• Self-explanatory code (getters, simple functions)
• Implementation details that may change
• TODOs without context (use issue tracker instead)

---

JSDoc/TSDoc Format

Functions

/**
 * Calculates the total price including tax and discounts.
 *
 * @param items - Cart items with quantity and unit price
 * @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
 * @param discountCode - Optional discount code to apply
 * @returns Total price in cents
 *
 * @example
 * ```ts
 * const total = calculateTotal(
 *   [{ quantity: 2, unitPrice: 1000 }],
 *   0.08,
 *   'SAVE10'
 * );
 * // Returns 1944 (2 * 1000 * 1.08 * 0.9)
 * ```
 *
 * @throws {InvalidDiscountError} If discount code is invalid or expired
 * @see {@link applyDiscount} for discount logic
 */
function calculateTotal(
  items: CartItem[],
  taxRate: number,
  discountCode?: string
): number {
  // ...
}

Interfaces/Types

/**
 * Represents a user in the system.
 *
 * @remarks
 * Users can be in different states during their lifecycle.
 * New users start as 'pending' until email verification.
 */
interface User {
  /** Unique identifier, UUID v4 format */
  id: string;

  /** User's email address, used for login */
  email: string;

  /**
   * Account status
   * - 'pending': Awaiting email verification
   * - 'active': Full access
   * - 'suspended': Temporarily disabled
   */
  status: 'pending' | 'active' | 'suspended';

  /**
   * When the user was created
   * @readonly Set automatically on creation
   */
  createdAt: Date;
}

Classes

/**
 * Manages WebSocket connections with automatic reconnection.
 *
 * @remarks
 * Uses exponential backoff for reconnection attempts.
 * Maximum 5 retry attempts before giving up.
 *
 * @example
 * ```ts
 * const ws = new WebSocketManager('wss://api.example.com');
 * ws.on('message', handleMessage);
 * ws.connect();
 * ```
 */
class WebSocketManager {
  /**
   * Creates a new WebSocket manager.
   * @param url - WebSocket server URL
   * @param options - Connection options
   */
  constructor(url: string, options?: WebSocketOptions) {
    // ...
  }
}

---

Inline Comments

Good Comments

// We use a Set here because we need O(1) lookups and uniqueness
const processedIds = new Set();

// HACK: API returns dates as strings in non-ISO format
// Remove this when backend is updated (JIRA-1234)
const date = parseCustomDateFormat(response.date);

// Intentionally not using optional chaining here
// to throw early if config is missing
const apiKey = config.api.key;

Bad Comments

// Increment counter
counter++;

// Loop through users
for (const user of users) {

// Set name to "John"
name = "John";

---

Output Structure

When --output is specified, create documentation file(s):

For Single File

# module-name

Brief description of the module.

## Functions

### functionName

Description...

**Parameters:**
- `param1` (Type): Description
- `param2` (Type, optional): Description

**Returns:** Type - Description

**Example:**
```code```

**Throws:**
- ErrorType: When...

---

## Types

### TypeName

Description...

**Properties:**
| Name | Type | Description |
|------|------|-------------|
| prop | Type | Description |

For Directory

Create individual docs or a combined API reference.

---

Flags

• --format=jsdoc: Use JSDoc format (default for JS)
• --format=tsdoc: Use TSDoc format (default for TS)
• --format=markdown: Generate markdown documentation
• --output=path: Write documentation to file (creates if doesn't exist)

---

Process

1. Analyze the Code

• Identify public API surface
• Understand function purposes
• Find complex or non-obvious logic

2. Generate Documentation

• Write clear, concise descriptions
• Add examples for complex usage
• Document edge cases and errors

3. Apply or Output

• If --output: Create documentation file
• Otherwise: Add doc comments to source code

---

What NOT to Do

• ❌ Document every line
• ❌ Repeat what the code clearly shows
• ❌ Leave outdated documentation
• ❌ Write documentation without understanding the code
• ❌ Skip examples for complex functions

---

Your Task

1. Read the specified file(s) or directory
2. Identify what needs documentation
3. Generate appropriate documentation
4. If --output specified, create the documentation file
5. Otherwise, add doc comments to the source code

Now document: $ARGUMENTS