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):

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:

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

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

"""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

# Project Name

Brief description of what this project does.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

```bash
pip install project-name

Quick Start

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

API Reference

See API docs for full reference.

Contributing

See CONTRIBUTING.md

License

MIT License - see 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