def process_user_data(user_id: int, options: dict = None) -> UserResult:
    """
    Retrieves and processes user data from the database.

    Args:
        user_id: Unique identifier for the user
        options: Optional processing flags

    Returns:
        UserResult object containing processed data

    Raises:
        UserNotFoundError: If user doesn't exist
    """

# handles auth token refresh
# returns the new token
def refresh_token(old_token):
    # call the auth API
    # parse response
    # save to secure storage
    pass

def refresh_token(old_token: str) -> str:
    """
    Refreshes an expired authentication token by calling the auth API.

    This function exchanges the provided expired token for a new valid
    token. The new token is automatically persisted to secure storage.

    Args:
        old_token (str): The current expired authentication token

    Returns:
        str: A new valid authentication token

    Raises:
        AuthAPIError: If the auth service is unreachable or returns an error
        InvalidTokenError: If the old_token is invalid or revoked

    Example:
        >>> new_token = refresh_token("expired_token_123")
        >>> print(new_token)
        "new_valid_token_456"
    """

#!/usr/bin/env python3
import anthropic
import glob
import os

def generate_api_docs(source_dir: str, output_dir: str):
    """Convert Python docstrings into Markdown API docs."""

    client = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

    # Find all Python files
    python_files = glob.glob(f"{source_dir}/**/*.py", recursive=True)

    for file_path in python_files:
        with open(file_path, 'r') as f:
            source_code = f.read()

        # Extract docstrings and comments
        message = client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=2000,
            messages=[{
                "role": "user",
                "content": f"""Convert this Python file's docstrings into professional Markdown documentation.
Include:
- Function signatures with parameter types
- Return value descriptions
- Example usage for each function
- Any warnings or gotchas mentioned in comments

Source file: {file_path}

{source_code}

Generate ONLY the Markdown output, no extra text."""
            }]
        )

        # Save documentation
        doc_file = output_dir + "/" + os.path.basename(file_path).replace('.py', '.md')
        with open(doc_file, 'w') as f:
            f.write(message.content[0].text)

        print(f"Generated: {doc_file}")

if __name__ == "__main__":
    generate_api_docs("src/", "docs/api/")

def process_data(x):
    # do the thing
    y = x * 2
    return y

def process_data(data: list[int]) -> list[int]:
    """
    Double each element in the input list.

    Used for scaling metrics before visualization.
    Note: Assumes positive integers only.

    Args:
        data: List of numeric values to scale

    Returns:
        List with each element multiplied by 2
    """
    return [x * 2 for x in data]

# Strategy 1: Have AI write comprehensive comments first
def legacy_function(a, b, c):
    result = a + (b * c)
    if result > 100:
        result = 100
    return result

# Ask Claude: "Write detailed comments for this function"
# Claude generates:
def legacy_function(a: int, b: int, c: int) -> int:
    """
    Calculate a weighted sum with upper bound capping.

    Computes: a + (b × c), then caps result at 100.

    Used in: Score normalization for user ratings
    See: metrics/rating.py for context

    Args:
        a: Base score (0-100)
        b: Weight factor (0-10)
        c: Adjustment multiplier (0-10)

    Returns:
        Capped result (max 100)
    """
    result = a + (b * c)
    if result > 100:
        result = 100
    return result

# Strategy 2: Then generate documentation from enhanced comments

def generate_all_formats(source_code: str):
    client = anthropic.Anthropic()

    formats = {
        "markdown": "Generate Markdown API documentation",
        "html": "Generate HTML documentation suitable for GitHub Pages",
        "docstring": "Enhance and rewrite docstrings in Google format",
        "confluence": "Generate Confluence wiki markup",
        "swagger": "Generate OpenAPI/Swagger specification"
    }

    outputs = {}
    for format_name, prompt_instruction in formats.items():
        message = client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=2000,
            messages=[{
                "role": "user",
                "content": f"{prompt_instruction}:\n\n{source_code}"
            }]
        )
        outputs[format_name] = message.content[0].text

    return outputs

# Quality checks for AI-generated docs
def check_doc_quality(markdown_file: str) -> dict:
    with open(markdown_file) as f:
        content = f.read()

    return {
        "has_examples": "Example:" in content or "```" in content,
        "has_parameters": "Args:" in content or "Parameters:" in content,
        "has_returns": "Returns:" in content,
        "has_errors": "Raises:" in content or "Errors:" in content,
        "line_count": len(content.split('\n')),
        "code_blocks": content.count("```")
    }

# Monitor these metrics weekly
# If examples or error documentation drops below threshold,
# retrain your documentation generation prompts