tomevault-io Documentation Writing
Core Principles
- Audience-focused - Know who you're writing for
- Task-oriented - Help users accomplish goals
- Scannable - Use headers, lists, and code blocks
- Accurate - Keep in sync with code
- Complete - Cover common use cases and edge cases
README Structure
# Project Name
Brief description (1-2 sentences).
## Features
- Feature 1
- Feature 2
## Installation
```bash
npm install package-name
Quick Start
import { thing } from 'package-name';
// Minimal working example
Usage
Basic Usage
Detailed examples with explanations.
Advanced Usage
Complex scenarios and configuration.
API Reference
Link to detailed docs or inline reference.
Contributing
How to contribute to the project.
License
MIT
## JSDoc/TSDoc Comments
### Functions
```typescript
/**
* Calculates the total price including tax.
*
* @param basePrice - The price before tax
* @param taxRate - Tax rate as a decimal (e.g., 0.08 for 8%)
* @returns The total price with tax applied
*
* @example
* ```ts
* const total = calculateTotal(100, 0.08);
* // Returns: 108
* ```
*
* @throws {RangeError} If taxRate is negative
*/
function calculateTotal(basePrice: number, taxRate: number): number {
if (taxRate < 0) throw new RangeError('Tax rate cannot be negative');
return basePrice * (1 + taxRate);
}
Classes
/**
* Manages user authentication and session state.
*
* @remarks
* This class handles OAuth2 authentication flows and maintains
* session tokens in secure storage.
*
* @example
* ```ts
* const auth = new AuthManager({ clientId: 'xxx' });
* await auth.login();
* const user = auth.getCurrentUser();
* ```
*/
class AuthManager {
/**
* Creates a new AuthManager instance.
* @param config - Authentication configuration options
*/
constructor(config: AuthConfig) {}
/**
* Initiates the login flow.
* @returns Promise that resolves when authentication completes
*/
async login(): Promise<void> {}
}
Interfaces
/**
* Configuration options for the API client.
*/
interface ApiClientConfig {
/**
* Base URL for all API requests.
* @example "https://api.example.com/v1"
*/
baseUrl: string;
/**
* Request timeout in milliseconds.
* @default 30000
*/
timeout?: number;
/**
* Custom headers to include in all requests.
*/
headers?: Record<string, string>;
}
API Documentation
OpenAPI/Swagger
openapi: 3.0.3
info:
title: User API
version: 1.0.0
description: API for managing users
paths:
/users:
get:
summary: List all users
description: Returns a paginated list of users
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
meta:
$ref: '#/components/schemas/Pagination'
Endpoint Documentation
## Create User
Creates a new user account.
### Request
`POST /api/v1/users`
#### Headers
| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |
#### Body
```json
{
"email": "user@example.com",
"name": "John Doe",
"role": "user"
}
| Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | Valid email address | |
| name | string | Yes | 2-100 characters |
| role | string | No | "user" or "admin" (default: "user") |
Response
Success (201 Created)
{
"success": true,
"data": {
"id": "usr_abc123",
"email": "user@example.com",
"name": "John Doe",
"createdAt": "2025-01-02T12:00:00Z"
}
}
Error (400 Bad Request)
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request body",
"details": {
"email": "Invalid email format"
}
}
}
## Code Examples
### Good Example
```typescript
// ✅ Shows real use case with context
import { createClient } from 'my-api';
const client = createClient({
apiKey: process.env.API_KEY,
region: 'us-east-1',
});
// Fetch user with error handling
try {
const user = await client.users.get('user_123');
console.log(`Found user: ${user.name}`);
} catch (error) {
if (error.code === 'NOT_FOUND') {
console.log('User does not exist');
} else {
throw error; // Re-throw unexpected errors
}
}
Bad Example
// ❌ Too abstract, no context
const client = new Client(options);
const result = client.doThing(data);
Changelog Format
# Changelog
## [1.2.0] - 2025-01-02
### Added
- New `exportToPDF()` method for reports (#123)
- Support for custom themes
### Changed
- Improved performance of data loading by 40%
- Updated minimum Node.js version to 18
### Fixed
- Fixed memory leak in long-running processes (#456)
- Corrected timezone handling for scheduled tasks
### Deprecated
- `legacyExport()` - use `exportToPDF()` instead
### Security
- Updated dependencies to patch CVE-2025-XXXX
Best Practices
- Write for scanning - Use headers, bullets, tables
- Show, don't tell - Include working code examples
- Keep examples minimal - Show the concept, not everything
- Update with code - Docs rot faster than code
- Test your examples - Ensure they actually work
- Link liberally - Connect related concepts
- Use consistent terminology - Define terms once
- Include troubleshooting - Common errors and solutions
Source: autohandai/community-skills — distributed by TomeVault.