claudekit/.claude/commands/doc.md

/doc - Documentation Command

Purpose

Generate or update documentation including API docs, README files, code comments, and technical specifications.

Usage

/doc [target | 'api' | 'readme' | 'changelog']

Arguments

• $ARGUMENTS:
  • File/function path: Document specific code
  • api: Generate API documentation
  • readme: Update README file
  • changelog: Generate changelog from commits

---

Generate documentation for: $ARGUMENTS

Workflow

For Code Documentation

1. Analyze Code

   • Read the code thoroughly
   • Understand purpose and behavior
   • Identify inputs and outputs
   • Note side effects

2. Generate Documentation

   • Add docstrings/JSDoc
   • Include examples
   • Document edge cases
   • Add type annotations

For API Documentation

1. Find All Endpoints

   • Scan route definitions
   • Identify HTTP methods
   • Note authentication requirements

2. Document Each Endpoint

   • Request format
   • Response format
   • Error responses
   • Examples

For README

1. Analyze Project

   • Purpose and features
   • Installation steps
   • Usage examples
   • Configuration

2. Generate/Update

   • Clear structure
   • Working examples
   • Up-to-date info

For Changelog

1. Analyze Commits

   git log --oneline --since="last release"
   

2. Categorize Changes

   • Added
   • Changed
   • Fixed
   • Removed

Templates

Python Docstring

def calculate_discount(price: float, percentage: float) -> float:
    """
    Calculate discounted price.

    Args:
        price: Original price in dollars.
        percentage: Discount percentage (0-100).

    Returns:
        The discounted price.

    Raises:
        ValueError: If percentage is not between 0 and 100.

    Example:
        >>> calculate_discount(100.0, 20)
        80.0
    """

TypeScript JSDoc

/**
 * Calculate discounted price.
 *
 * @param price - Original price in dollars
 * @param percentage - Discount percentage (0-100)
 * @returns The discounted price
 * @throws {RangeError} If percentage is not between 0 and 100
 *
 * @example
 * calculateDiscount(100, 20); // returns 80
 */

API Endpoint

## POST /api/orders

Create a new order.

### Authentication
Requires Bearer token.

### Request Body
```json
{
  "items": [
    { "productId": "123", "quantity": 2 }
  ],
  "shippingAddress": {
    "street": "123 Main St",
    "city": "New York",
    "zip": "10001"
  }
}

Response (201 Created)

{
  "id": "order_456",
  "status": "pending",
  "total": 99.99,
  "createdAt": "2024-01-15T10:00:00Z"
}

Errors

Status	Code	Description
400	INVALID_ITEMS	Items array is empty
401	UNAUTHORIZED	Invalid or missing token
422	OUT_OF_STOCK	Item not available

### README Section
```markdown
## Installation

```bash
npm install my-package

Quick Start

import { Client } from 'my-package';

const client = new Client({ apiKey: 'your-key' });
const result = await client.fetch();

Configuration

Option	Type	Default	Description
apiKey	string	required	Your API key
timeout	number	5000	Request timeout in ms

### Changelog Entry
```markdown
## [1.2.0] - 2024-01-15

### Added
- Password reset functionality (#123)
- Email verification for new accounts

### Changed
- Improved error messages for validation failures
- Updated dependencies to latest versions

### Fixed
- Race condition in session handling (#456)
- Incorrect timezone in date displays

Output

Documentation Report

## Documentation Updated

### Files Modified
- `src/services/auth.ts` - Added JSDoc comments
- `docs/api/auth.md` - New API documentation
- `README.md` - Updated configuration section

### Documentation Added

#### Code Comments
- `AuthService.login()` - Full JSDoc with examples
- `AuthService.logout()` - Parameter documentation
- `validateToken()` - Return type and exceptions

#### API Documentation
- POST /api/auth/login
- POST /api/auth/logout
- POST /api/auth/refresh

### Coverage
- Functions documented: 15/18 (83%)
- Endpoints documented: 12/12 (100%)

### Next Steps
1. Add examples to remaining functions
2. Create getting started guide
3. Add architecture diagram

Variations

Modify behavior via CLAUDE.md:

• Documentation format
• Required sections
• Example requirements
• API documentation tool