# Read existing code/project structure
# Identify documentation needs
# Generate appropriate documentation format
# Include examples and usage patterns

def calculate_total(items: list[dict], tax_rate: float = 0.1) -> float:
    """Calculate total price including tax for a list of items.
    
    Takes a list of items with prices and calculates the total cost
    including the specified tax rate.
    
    Args:
        items: List of item dictionaries with 'price' keys
        tax_rate: Tax rate as decimal (default: 0.1 for 10%)
    
    Returns:
        Total price including tax, rounded to 2 decimal places
    
    Raises:
        ValueError: If items list is empty or contains invalid prices
        TypeError: If items is not a list
    
    Examples:
        >>> items = [{'price': 10.0}, {'price': 20.0}]
        >>> calculate_total(items)
        33.0
        
        >>> calculate_total(items, tax_rate=0.2)
        36.0
    """
    if not isinstance(items, list):
        raise TypeError("items must be a list")
    if not items:
        raise ValueError("items list cannot be empty")
    
    subtotal = sum(item['price'] for item in items)
    total = subtotal * (1 + tax_rate)
    return round(total, 2)

/**
 * Fetches user data from the API with error handling and caching
 * 
 * @param {string} userId - The unique identifier for the user
 * @param {Object} options - Configuration options
 * @param {boolean} options.useCache - Whether to use cached data (default: true)
 * @param {number} options.timeout - Request timeout in milliseconds (default: 5000)
 * 
 * @returns {Promise<User>} Promise resolving to User object
 * 
 * @throws {UserNotFoundError} When user doesn't exist
 * @throws {NetworkError} When network request fails
 * @throws {TimeoutError} When request exceeds timeout
 * 
 * @example
 * // Basic usage
 * const user = await fetchUser('user123');
 * 
 * @example
 * // With options
 * const user = await fetchUser('user123', {
 *   useCache: false,
 *   timeout: 10000
 * });
 */
async function fetchUser(
  userId: string,
  options: FetchOptions = {}
): Promise<User> {
  // Implementation...
}

/**
 * Processes payment transactions with validation and fraud detection.
 * 
 * <p>This method validates the payment details, checks for fraudulent activity,
 * and processes the transaction through the payment gateway. All operations
 * are performed within a database transaction for consistency.
 * 
 * @param payment the payment details including amount and method
 * @param customer the customer making the payment
 * @return a {@link PaymentResult} containing transaction ID and status
 * 
 * @throws InsufficientFundsException if the payment amount exceeds available funds
 * @throws FraudDetectedException if the transaction is flagged as fraudulent
 * @throws PaymentGatewayException if the payment gateway returns an error
 * 
 * @see PaymentValidator
 * @see FraudDetector
 * @since 2.0
 * 
 * @example
 * <pre>
 * Payment payment = new Payment(100.0, PaymentMethod.CREDIT_CARD);
 * Customer customer = customerService.findById("customer123");
 * PaymentResult result = paymentProcessor.process(payment, customer);
 * System.out.println("Transaction ID: " + result.getTransactionId());
 * </pre>
 */
public PaymentResult process(Payment payment, Customer customer)
    throws InsufficientFundsException, FraudDetectedException, PaymentGatewayException {
    // Implementation...
}

# Project Name

Brief description of what this project does and why it's useful.

[![Build Status](badge-url)](link)
[![Coverage](badge-url)](link)
[![License](badge-url)](link)

## Features

- 🚀 Feature 1: Description
- 📦 Feature 2: Description
- 🔒 Feature 3: Description

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [Configuration](#configuration)
- [API Documentation](#api-documentation)
- [Contributing](#contributing)
- [License](#license)

## Installation

### Prerequisites

- Node.js >= 14.0.0
- Python >= 3.8
- PostgreSQL >= 12

### Setup

```bash
# Clone the repository
git clone https://github.com/username/project.git

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Run migrations
npm run migrate

# Start development server
npm run dev

const Client = require('project-name');

const client = new Client({
  apiKey: 'your-api-key'
});

const result = await client.doSomething();
console.log(result);

{
  "setting1": "value1",
  "setting2": "value2"
}

const result = client.method('value', 42);

## Architecture Decision Records (ADR)

Template for documenting architecture decisions:

```markdown
# ADR-001: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded]

## Context
What is the issue we're facing? What are the constraints?

## Decision
What decision are we making? What alternative did we choose?

## Consequences
What are the positive and negative consequences of this decision?

### Positive
- Benefit 1
- Benefit 2

### Negative
- Trade-off 1
- Trade-off 2

### Neutral
- Consideration 1

## Alternatives Considered

### Alternative 1
- Description
- Why it was rejected

### Alternative 2
- Description
- Why it was rejected

## References
- Link to relevant discussions
- Link to related documentation

docs/
├── README.md                 # Project overview
├── CONTRIBUTING.md          # Contribution guidelines
├── CHANGELOG.md             # Version history
├── architecture/
│   ├── overview.md         # System architecture
│   ├── adr/                # Architecture decisions
│   │   ├── 001-database-choice.md
│   │   └── 002-api-design.md
│   └── diagrams/           # Architecture diagrams
├── api/
│   ├── reference.md        # Complete API reference
│   └── examples.md         # API usage examples
├── guides/
│   ├── getting-started.md  # Quick start guide
│   ├── tutorials/          # Step-by-step tutorials
│   └── how-to/             # Task-specific guides
└── reference/
    ├── configuration.md    # Configuration reference
    └── troubleshooting.md  # Common issues