tomevault-io API Documentation
Best practices for documenting APIs and code interfaces. Eliminates ~100-150 lines of redundant documentation guidance per agent.
Core Documentation Principles
- Document the why, not just the what - Explain intent and rationale
- Keep docs close to code - Inline documentation stays synchronized
- Document contracts, not implementation - Focus on behavior
- Examples are essential - Show real usage
- Update docs with code - Outdated docs are worse than no docs
Function/Method Documentation
Python (Docstrings)
def calculate_discount(price: float, discount_percent: float) -> float:
"""
Calculate discounted price with percentage off.
Args:
price: Original price in dollars (must be positive)
discount_percent: Discount percentage (0-100)
Returns:
Final price after discount, rounded to 2 decimals
Raises:
ValueError: If price is negative or discount > 100
Examples:
>>> calculate_discount(100.0, 20.0)
80.0
>>> calculate_discount(50.0, 50.0)
25.0
Note:
Discount percent is capped at 100% (minimum price of 0)
"""
if price < 0:
raise ValueError("Price cannot be negative")
if discount_percent > 100:
raise ValueError("Discount cannot exceed 100%")
discount_amount = price * (discount_percent / 100)
return round(price - discount_amount, 2)
JavaScript (JSDoc)
/**
* Calculate discounted price with percentage off
*
* @param {number} price - Original price in dollars (must be positive)
* @param {number} discountPercent - Discount percentage (0-100)
* @returns {number} Final price after discount, rounded to 2 decimals
* @throws {Error} If price is negative or discount > 100
*
* @example
* calculateDiscount(100.0, 20.0)
* // returns 80.0
*
* @example
* calculateDiscount(50.0, 50.0)
* // returns 25.0
*/
function calculateDiscount(price, discountPercent) {
if (price < 0) {
throw new Error('Price cannot be negative');
}
if (discountPercent > 100) {
throw new Error('Discount cannot exceed 100%');
}
const discountAmount = price * (discountPercent / 100);
return Math.round((price - discountAmount) * 100) / 100;
}
Go (Godoc)
// CalculateDiscount calculates discounted price with percentage off.
//
// The function applies the given discount percentage to the original price
// and returns the final price rounded to 2 decimal places.
//
// Parameters:
// - price: Original price in dollars (must be positive)
// - discountPercent: Discount percentage (0-100)
//
// Returns the final price after discount.
//
// Returns an error if price is negative or discount exceeds 100%.
//
// Example:
//
// finalPrice, err := CalculateDiscount(100.0, 20.0)
// // finalPrice = 80.0
func CalculateDiscount(price, discountPercent float64) (float64, error) {
if price < 0 {
return 0, errors.New("price cannot be negative")
}
if discountPercent > 100 {
return 0, errors.New("discount cannot exceed 100%")
}
discountAmount := price * (discountPercent / 100)
return math.Round((price-discountAmount)*100) / 100, nil
}
API Endpoint Documentation
REST API (OpenAPI/Swagger)
openapi: 3.0.0
info:
title: User Management API
version: 1.0.0
paths:
/users/{userId}:
get:
summary: Get user by ID
description: Retrieves detailed information for a specific user
parameters:
- name: userId
in: path
required: true
schema:
type: integer
minimum: 1
description: Unique user identifier
responses:
'200':
description: User found successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
example:
id: 123
name: "John Doe"
email: "john@example.com"
'404':
description: User not found
'401':
description: Unauthorized - authentication required
GraphQL
"""
Represents a user in the system
"""
type User {
"""Unique identifier for the user"""
id: ID!
"""User's full name"""
name: String!
"""User's email address (validated)"""
email: String!
"""User's posts (paginated)"""
posts(limit: Int = 10, offset: Int = 0): [Post!]!
}
"""
Query a specific user by ID
"""
type Query {
"""
Get user by unique identifier
Returns null if user not found
"""
user(id: ID!): User
}
Class/Module Documentation
class UserManager:
"""
Manages user accounts and authentication.
This class provides a high-level interface for user management
operations including creation, authentication, and profile updates.
Attributes:
db: Database connection instance
cache: Redis cache for session management
Example:
>>> manager = UserManager(db=get_db(), cache=get_cache())
>>> user = manager.create_user("john@example.com", "password")
>>> authenticated = manager.authenticate("john@example.com", "password")
>>> authenticated is not None
True
Thread Safety:
This class is thread-safe. Multiple threads can safely call
methods concurrently.
Note:
All passwords are automatically hashed using bcrypt before
storage. Never pass pre-hashed passwords to methods.
"""
def __init__(self, db: Database, cache: Cache):
"""
Initialize UserManager with database and cache.
Args:
db: Database connection for persistent storage
cache: Redis cache for session management
Raises:
ConnectionError: If unable to connect to database or cache
"""
self.db = db
self.cache = cache
README Documentation Structure
# Project Name
Brief description of what the project does (1-2 sentences).
## Features
- Key feature 1
- Key feature 2
- Key feature 3
## Installation
```bash
pip install project-name
Quick Start
from project import MainClass
# Simple usage example
client = MainClass(api_key="your-key")
result = client.do_something()
print(result)
Configuration
| Option | Type | Default | Description |
|---|---|---|---|
api_key |
str | None | API authentication key |
timeout |
int | 30 | Request timeout in seconds |
API Reference
See full API Documentation
Main Methods
do_something(param1, param2)
Description of what this does.
Parameters:
param1(str): Description of param1param2(int): Description of param2
Returns: Description of return value
Example:
result = client.do_something("value", 42)
Contributing
See CONTRIBUTING.md
License
MIT License - see LICENSE
## Documentation Anti-Patterns
### ❌ Redundant Comments
```python
# Bad: Obvious comment adds no value
i = i + 1 # Increment i
# Good: Comment explains WHY
i = i + 1 # Skip header row
❌ Outdated Documentation
# Bad: Comment doesn't match code
def get_users(limit=10): # Comment says: Returns all users
"""Returns all users in the system.""" # But limit is 10!
return User.query.limit(limit).all()
# Good: Keep docs synchronized
def get_users(limit=10):
"""
Returns up to 'limit' users from the system.
Args:
limit: Maximum number of users to return (default: 10)
"""
return User.query.limit(limit).all()
❌ Implementation Documentation
# Bad: Documents HOW (implementation)
def sort_users(users):
"""Uses bubble sort algorithm to sort users.""" # Don't care!
...
# Good: Documents WHAT (contract)
def sort_users(users):
"""Returns users sorted alphabetically by name."""
...
Documentation Tools
Python
- Sphinx: Generate HTML docs from docstrings
- pdoc: Simpler alternative to Sphinx
- MkDocs: Markdown-based documentation
JavaScript
- JSDoc: Generate HTML from JSDoc comments
- TypeDoc: For TypeScript projects
- Docusaurus: Full documentation websites
Go
- godoc: Built-in documentation tool
- pkgsite: Go package documentation
Rust
- rustdoc: Built-in documentation with
cargo doc
Quick Documentation Checklist
□ Public APIs have docstrings/comments
□ Parameters and return values documented
□ Exceptions/errors documented
□ Usage examples provided
□ Edge cases and limitations noted
□ README includes quick start
□ API reference available
□ Configuration options documented
□ Docs are up to date with code
□ Breaking changes documented
Remember
- Code is read more than written - Good docs save time
- Examples speak louder than descriptions - Show, don't just tell
- The best docs are no docs - Write self-documenting code
- Keep it DRY - Don't repeat what the code already says
- Update docs with code - Outdated docs mislead developers
Converted and distributed by TomeVault — claim your Tome and manage your conversions.