// Bad: Documents what the code does (obvious from code)
// Increments counter by 1

// Good: Documents why
// Prevents race condition by using atomic increment

# Project Name

One-sentence description of what this does.

## Quick Start

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

\`\`\`typescript
import { main } from 'package-name';
main();
\`\`\`

## Features

- Feature 1 - brief description
- Feature 2 - brief description

## Installation

Detailed installation instructions.

## Usage

### Basic Usage
...

### Advanced Usage
...

## API Reference

Link to detailed API docs or inline reference.

## Configuration

Environment variables, config files.

## Contributing

How to contribute.

## License

License information.

/**
 * Calculates the total price including tax.
 *
 * @param items - Array of items with price property
 * @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
 * @returns Total price with tax applied
 *
 * @example
 * ```typescript
 * const items = [{ price: 10 }, { price: 20 }];
 * calculateTotal(items, 0.08); // 32.40
 * ```
 *
 * @throws {Error} If taxRate is negative
 */
function calculateTotal(items: Item[], taxRate: number): number {
  // implementation
}

def calculate_total(items: list[Item], tax_rate: float) -> float:
    """Calculate the total price including tax.

    Args:
        items: List of items with price attribute.
        tax_rate: Tax rate as decimal (e.g., 0.08 for 8%).

    Returns:
        Total price with tax applied.

    Raises:
        ValueError: If tax_rate is negative.

    Example:
        >>> items = [Item(price=10), Item(price=20)]
        >>> calculate_total(items, 0.08)
        32.40
    """

# Install
bun add -d typedoc

# Generate
bunx typedoc --out docs src/index.ts

# Install
pip install sphinx sphinx-autodoc-typehints

# Generate
sphinx-apidoc -o docs/api src/
sphinx-build -b html docs docs/_build

## Documentation
- [ ] README updated (if public API changed)
- [ ] JSDoc/docstrings added for new functions
- [ ] CHANGELOG updated
- [ ] Migration guide updated (if breaking change)

// In test file
import { exampleCode } from '../docs/examples';

test('documentation examples work', async () => {
  // Run the example code from docs
  const result = await exampleCode();
  expect(result).toBeDefined();
});

// Before
function processData(data, options) {
  // ...
}

// After
/**
 * Processes raw data according to specified options.
 *
 * @param data - Raw data to process
 * @param options - Processing configuration
 * @param options.validate - Whether to validate input (default: true)
 * @param options.transform - Transform function to apply
 * @returns Processed data object
 *
 * @example
 * ```typescript
 * const result = processData(rawData, { validate: true });
 * ```
 */
function processData(data: RawData, options: ProcessOptions): ProcessedData {
  // ...
}

# {package-name}

{one-line-description}

[![npm version](https://badge.fury.io/js/{package-name}.svg)](https://www.npmjs.com/package/{package-name})

## Installation

\`\`\`bash
npm install {package-name}
# or
bun add {package-name}
\`\`\`

## Quick Start

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

const result = main();
console.log(result);
\`\`\`

## API

### `main(options?)`

Main entry point.

**Parameters:**
- `options.debug` (boolean): Enable debug mode

**Returns:** Result object

## License

MIT