API Documentation

API Documentation

Purpose

Create comprehensive API documentation that enables developers to quickly understand and correctly use APIs, including parameters, return values, errors, and practical examples.

When to Use

• Documenting public APIs
• Creating developer references
• Writing SDK documentation
• Updating API changes

Key Capabilities

1. Signature Documentation - Clear parameter and return type descriptions
2. Example Creation - Practical, working code examples
3. Error Documentation - All possible errors and when they occur

Approach

1. Document function signature with types
2. Describe each parameter clearly
3. Describe return value and possible states
4. List all exceptions/errors that can be raised
5. Provide working example code
6. Note version added or deprecated

Example

Context: Documenting a task creation function

### add_task(title, agent, priority, description)

Creates a new task in the queue.

**Parameters**:
- `title` (string) - Short descriptive title for the task
- `agent` (string) - Agent name to assign (must exist in agents.json)
- `priority` (string) - One of: "critical", "high", "normal", "low"
- `description` (string) - Detailed task description

**Returns**:
- `string` - Unique task ID for the created task

**Raises**:
- `ValueError` - If agent name is invalid or priority is unknown
- `FileNotFoundError` - If queue file cannot be accessed

**Example**:
```python
task_id = queue.add_task(
    title="Fix login bug",
    agent="implementer",
    priority="high",
    description="Users cannot log in with valid credentials"
)
print(f"Created task: {task_id}")
```

**Since**: v1.0.0

Best Practices

• ✅ Include type information for all parameters
• ✅ Provide complete, working examples
• ✅ Document all possible errors
• ❌ Avoid: Incomplete or outdated examples