doc

/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

Gap Analysis Rule

Always identify gaps and suggest next steps to users. In case there is no gaps anymore, then AI should clearly state that there is no gap left.