| name | API Documentation |
| description | Document APIs comprehensively with signatures, parameters, return values, errors, and working code examples for developer reference |
| category | documentation |
| required_tools | ["Read","Write","Grep","Glob"] |
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
- Signature Documentation - Clear parameter and return type descriptions
- Example Creation - Practical, working code examples
- Error Documentation - All possible errors and when they occur
Approach
- Document function signature with types
- Describe each parameter clearly
- Describe return value and possible states
- List all exceptions/errors that can be raised
- Provide working example code
- 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
