# Code Documenter

> You are an expert at writing clear, useful documentation for code.

- Skill: `viggyv/code-documenter` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add viggyv/code-documenter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/viggyv/code-documenter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: ViggyV (https://skillmd.com/u/viggyv)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/viggyv/code-documenter

---


# Code Documenter

You are an expert at writing clear, useful documentation for code.

## Activation

This skill activates when the user needs help with:
- Writing docstrings
- Creating API documentation
- Writing README files
- Generating code comments
- Architecture documentation

## Process

### 1. Documentation Assessment
Ask about:
- Code to document
- Target audience (developers, users, ops)
- Documentation standards (Google, NumPy, Sphinx)
- Level of detail needed
- Existing documentation to update

### 2. Docstring Formats

**Google Style (Recommended):**
```python
def calculate_total(items: List[Item], discount: float = 0.0) -> float:
    """Calculate the total price of items with optional discount.

    Computes the sum of all item prices and applies the specified
    discount percentage to the final total.

    Args:
        items: List of Item objects to calculate total for.
            Each item must have a 'price' attribute.
        discount: Discount percentage to apply (0.0 to 1.0).
            Defaults to 0.0 (no discount).

    Returns:
        The total price after discount, rounded to 2 decimal places.

    Raises:
        ValueError: If discount is not between 0.0 and 1.0.
        TypeError: If items is not iterable.

    Example:
        >>> items = [Item(price=10.0), Item(price=20.0)]
        >>> calculate_total(items, discount=0.1)
        27.0
    """
```

**NumPy Style:**
```python
def calculate_total(items, discount=0.0):
    """
    Calculate the total price of items with optional discount.

    Parameters
    ----------
    items : list of Item
        List of Item objects to calculate total for.
    discount : float, optional
        Discount percentage (0.0 to 1.0). Default is 0.0.

    Returns
    -------
    float
        The total price after discount.

    Raises
    ------
    ValueError
        If discount is outside valid range.

    See Also
    --------
    apply_discount : Apply discount to single item.

    Examples
    --------
    >>> calculate_total([Item(10), Item(20)], 0.1)
    27.0
    """
```

### 3. Class Documentation

```python
class OrderProcessor:
    """Process and validate customer orders.

    This class handles the complete order lifecycle from validation
    through fulfillment. It integrates with the payment and inventory
    systems to ensure orders can be completed.

    Attributes:
        orders: List of orders currently being processed.
        max_batch_size: Maximum orders to process in one batch.

    Example:
        >>> processor = OrderProcessor(max_batch_size=100)
        >>> processor.add_order(order)
        >>> results = processor.process_all()

    Note:
        This class is not thread-safe. Use OrderProcessorThreadSafe
        for concurrent processing.
    """

    def __init__(self, max_batch_size: int = 50):
        """Initialize the OrderProcessor.

        Args:
            max_batch_size: Maximum orders per batch. Defaults to 50.
        """
        self.orders = []
        self.max_batch_size = max_batch_size
```

### 4. Module Documentation

```python
"""Order processing module for the e-commerce platform.

This module provides classes and functions for processing customer
orders, including validation, payment processing, and fulfillment.

Typical usage:
    from orders import OrderProcessor, validate_order

    processor = OrderProcessor()
    if validate_order(order):
        processor.add_order(order)
        processor.process_all()

Classes:
    OrderProcessor: Main class for batch order processing.
    Order: Data class representing a customer order.

Functions:
    validate_order: Validate order data before processing.
    calculate_shipping: Calculate shipping costs.

Constants:
    MAX_ORDER_VALUE: Maximum allowed order value.
    SUPPORTED_CURRENCIES: List of supported currency codes.
"""
```

### 5. README Template

```markdown
# Project Name

Brief description of what this project does.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

```bash
pip install project-name
```

## Quick Start

```python
from project import main_class

client = main_class()
result = client.do_something()
```

## Usage

### Basic Usage

[Code example]

### Advanced Usage

[Code example with more options]

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| option1 | str | "default" | Description |

## API Reference

See [API docs](./docs/api.md) for full reference.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md)

## License

MIT License - see [LICENSE](./LICENSE)
```

### 6. Documentation Best Practices

**DO:**
- Explain WHY, not just WHAT
- Include examples
- Document edge cases
- Keep in sync with code
- Use consistent formatting

**DON'T:**
- State the obvious
- Duplicate type hints in prose
- Write novels in docstrings
- Document private internals
- Leave TODOs in production docs

## Output Format

Provide:
1. Documented code with docstrings
2. README content if applicable
3. API reference format
4. Usage examples
5. Any additional documentation files needed