doc-generator

Doc Generator

Version: 1.0.0 Purpose: Generate comprehensive documentation

Triggers

Documentation Types

1. JSDoc/TSDoc

/**
 * Calculates the total price including tax.
 *
 * @param items - Array of items with price property
 * @param taxRate - Tax rate as decimal (e.g., 0.1 for 10%)
 * @returns Total price including tax
 *
 * @example
 * ```ts
 * const total = calculateTotal([{ price: 100 }], 0.1);
 * // Returns: 110
 * ```
 *
 * @throws {Error} If items array is empty
 * @see {@link Item} for item structure
 */
function calculateTotal(items: Item[], taxRate: number): number {
  // implementation
}

2. Interface Documentation

/**
 * Represents a user in the system.
 *
 * @interface User
 * @property {string} id - Unique identifier
 * @property {string} email - User's email address
 * @property {Date} createdAt - Account creation timestamp
 */
interface User {
  id: string;
  email: string;
  createdAt: Date;
}

3. README Structure

# Project Name

> One-line description

[![npm](https://img.shields.io/npm/v/package-name)](https://npmjs.com/package/package-name)
[![License](https://img.shields.io/npm/l/package-name)](LICENSE)

## Features

- Feature 1
- Feature 2

## Installation

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

## Quick Start

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

const result = something();
\`\`\`

## API Reference

### `functionName(param)`

Description of function.

**Parameters:**
- `param` (Type) - Description

**Returns:** Type - Description

**Example:**
\`\`\`typescript
const result = functionName('value');
\`\`\`

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| option1 | string | 'default' | Description |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

MIT

4. CHANGELOG

# Changelog

All notable changes to this project will be documented in this file.

## [1.2.0] - 2025-01-15

### Added
- New feature X (#123)

### Changed
- Updated dependency Y

### Fixed
- Bug in Z (#124)

### Deprecated
- Old API method

### Removed
- Legacy code

### Security
- Fixed vulnerability

Workflow

Step 1: Analyze Code

# Find undocumented functions
grep -r "^export function" src/ | grep -v "/\*\*"

Step 2: Generate Docs

For each function/class:

1. Read implementation
2. Understand purpose
3. Write description
4. Add parameters
5. Add return type
6. Add examples

Step 3: Verify

# TypeScript doc check
npx typedoc --validation

# Lint docs
npx eslint --rule 'jsdoc/*' src/

Best Practices

Do

/**
 * Validates email format.
 *
 * @param email - Email address to validate
 * @returns True if email is valid
 */
function isValidEmail(email: string): boolean { }

Don't

/**
 * This function validates emails.
 * It takes an email parameter.
 * It returns a boolean.
 */
function isValidEmail(email: string): boolean { }

Templates

Function Doc

/**
 * [Brief description in imperative mood]
 *
 * [Longer description if needed]
 *
 * @param paramName - [Description]
 * @returns [Description]
 *
 * @example
 * \`\`\`ts
 * [Usage example]
 * \`\`\`
 *
 * @throws {ErrorType} [When this error occurs]
 * @since [version]
 * @deprecated [Use X instead]
 */

Class Doc

/**
 * [Brief description]
 *
 * [Longer description]
 *
 * @example
 * \`\`\`ts
 * const instance = new ClassName(options);
 * instance.method();
 * \`\`\`
 */
class ClassName { }

Checklist

• All public APIs documented
• Examples included
• Parameters described
• Return values described
• Errors documented
• README is current
• CHANGELOG updated