20. Documentation

Documentation is a lie you tell yourself: "I'll document it later." Later never comes. Document as you build, or accept that your knowledge will be lost.

Code-Level Documentation

Every public interface needs docstrings that answer: what, why, and how:

class MessageRouter:
    """
    Routes messages to registered handlers based on message type.
    
    The router maintains a registry of handlers keyed by message type.
    When a message arrives, the router dispatches it to the appropriate
    handler based on exact type matching.
    
    Thread Safety:
        This class is NOT thread-safe. Use with a single event loop
        or wrap dispatch in asyncio.Lock if multithreaded access needed.
    
    Example:
        >>> router = MessageRouter()
        >>> router.register("greeting", handle_greeting)
        >>> await router.route({"type": "greeting", "content": "hi"})
    """
    
    def __init__(self):
        self._handlers: dict[str, Callable] = {}

API Documentation

Generate API docs from code, don't maintain them separately:

## AgentRegistry.find_by_capability(capability)

**Parameters:**
- `capability` (str): The capability to search for (e.g., "text-generation")

**Returns:**
- `list[AgentRegistration]`: All agents that have the requested capability and have sent a heartbeat within the TTL window.

**Raises:**
- Nothing. Returns empty list if no matching agents found.

**Note:**
This method filters out agents that have missed heartbeats, ensuring
you don't route to agents that have crashed or become unreachable.

Architecture Decision Records

Document why decisions were made, not just what was built:

# ADR-012: Message Serialization Format

## Status
Accepted

## Context
We need a serialization format for agent messages that survives process 
restarts and can be read by monitoring tools.

## Decision
We will use JSON for message serialization, not pickle or protocol buffers.

## Consequences

### Positive
- Human-readable for debugging
- Compatible across Python versions
- No compilation step needed

### Negative
- Larger message sizes than binary formats
- No schema enforcement (runtime validation needed)
- Slower serialization than msgpack