/**
 * 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
}

/**
 * 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;
}

# 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

# 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

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

# TypeScript doc check
npx typedoc --validation

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

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

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

/**
 * [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]
 */

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