Documentation Generation

Documentation with ralph

Documentation is often neglected because it’s tedious. ralph makes it systematic—iterate until everything is documented.

Example: JSDoc Comments

Add JSDoc comments to all exported functions.

Setup

ralph init

Edit .ralph/config.toml:

adapter = "claude"
maxIterations = 40

Prompt (.plans/PROMPT.md)

# Add JSDoc Documentation

Add JSDoc comments to all exported functions, classes, and types.

## JSDoc Format

### Functions
```typescript
/**
 * Brief description of what the function does.
 *
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws {ErrorType} When this error occurs
 *
 * @example
 * ```typescript
 * const result = myFunction('input');
 * ```
 */
export function myFunction(paramName: string): ReturnType {

Classes

/**
 * Brief description of the class purpose.
 *
 * @example
 * ```typescript
 * const instance = new MyClass();
 * instance.doSomething();
 * ```
 */
export class MyClass {

Types/Interfaces

/**
 * Describes what this type represents.
 */
export interface MyInterface {
  /** Description of property */
  propertyName: string;
}

Rules

Document ALL exports (functions, classes, interfaces, types)
Include @param for every parameter
Include @returns for non-void functions
Include @throws for functions that throw
Include @example for complex functions
Keep descriptions concise but complete

Progress

Track completed files in progress.txt

Process

Run ESLint to find undocumented exports
Document one file at a time
Run ESLint again to verify
Commit: “docs(file): add JSDoc comments”

Completion

When npx eslint src/ --rule 'jsdoc/require-jsdoc: error' shows 0 errors, output: COMPLETE

## Example: README Generation

Generate README files for each package in a monorepo.

### Prompt

```markdown
# Generate Package READMEs

Create README.md files for each package in the monorepo.

## README Template

```markdown
# package-name

Brief description from package.json.

## Installation

\`\`\`bash
npm install package-name
\`\`\`

## Usage

\`\`\`typescript
import { mainExport } from 'package-name';

// Basic usage example
\`\`\`

## API

### `functionName(params): ReturnType`

Description of function.

**Parameters:**
- `param1` - Description

**Returns:** Description

## License

MIT

Progress

Track completed packages in progress.txt

Process

Find packages without README: find packages -maxdepth 2 -name 'package.json' -exec dirname {} \;
Read package.json and source code
Generate README following template
Commit: “docs(package): add README”

Completion

When every package directory has a README.md, output: COMPLETE

## Example: API Documentation

Generate OpenAPI/Swagger documentation from code.

### Prompt

```markdown
# Generate API Documentation

Add OpenAPI annotations to all API routes.

## Annotation Format (using tsoa)

```typescript
/**
 * @summary Get user by ID
 * @param userId The user's unique identifier
 * @returns User object
 */
@Get('{userId}')
@Response<NotFoundError>(404, 'User not found')
@Response<ValidationError>(400, 'Invalid user ID')
public async getUser(
  @Path() userId: string
): Promise<User> {

Documentation Requirements

Every route must have @summary
All parameters documented with @param
Response types documented with @Response
Error responses documented
Request body types defined

Process

Find undocumented routes
Add annotations
Run npm run docs:generate
Validate with npm run docs:validate
Commit

Completion

When npm run docs:validate passes, output: COMPLETE

## Tips for Documentation Tasks

### 1. Provide Examples

Include examples of good documentation:

```markdown
## Good JSDoc Example
[Include a well-documented function from your codebase]

2. Define Style Guidelines

Be explicit about style:

## Style Guidelines
- Use present tense ("Returns" not "Will return")
- Start with verb ("Gets the user" not "This function gets")
- Keep first line under 80 characters
- Use @example for anything non-obvious

3. Include Validation

Give the AI a way to check its work:

## Validation
Run `npm run lint:docs` to check documentation completeness.

4. Handle Edge Cases

Document how to handle tricky situations:

## Edge Cases
- Private methods: Don't document unless complex
- Generated code: Skip files in src/generated/
- Deprecated functions: Include @deprecated tag