code-documentation

# Code Documentation

This skill enables an AI agent to analyze source code and produce high-quality documentation in multiple formats. It covers everything from single-function docstrings to full project README files, ensuring that both human developers and downstream tooling (IDEs, doc generators) benefit from consistent, accurate descriptions.

## Workflow

1. **Inventory the Codebase**: Walk the project tree and catalog public modules, classes, functions, constants, and type definitions. Note which symbols already have documentation and which are missing or stale.

2. **Determine Documentation Scope**: Based on the user's request, decide whether to generate inline docstrings, a standalone API reference, a project-level README, or a combination. Match the output format to the project's existing conventions (JSDoc, Google-style Python docstrings, TypeDoc, RDoc, etc.).

3. **Analyze Signatures and Behavior**: For each symbol, inspect parameter types, return types, default values, raised exceptions, and side effects. Read surrounding test files when available to understand intended usage and edge cases.

4. **Generate Documentation**: Write documentation that includes a one-line summary, an extended description when the logic is non-trivial, parameter and return-value documentation with types, exception/error documentation, and at least one usage example for public API surfaces.

5. **Insert or Update In-Place**: For inline documentation (docstrings, JSDoc comments), insert the generated text directly above or inside the relevant symbol. For standalone files (README, API reference), create or update the Markdown file at the project root or a `docs/` directory.

6. **Validate and Cross-Reference**: Verify that documented parameter names match the actual signature, that referenced types exist, and that examples are syntactically valid. Flag any inconsistencies for the user to review.

## Supported Formats

- **Python**: Google-style docstrings, NumPy-style docstrings, Sphinx reStructuredText
- **JavaScript / TypeScript**: JSDoc (`@param`, `@returns`, `@throws`), TypeDoc annotations
- **Java**: Javadoc (`@param`, `@return`, `@throws`)
- **Go**: Godoc comment conventions (comment block immediately above the declaration)
- **Rust**: `///` doc comments with Markdown, `#[doc]` attributes
- **Ruby**: YARD (`@param`, `@return`, `@example`)
- **Markdown**: README files, CHANGELOG entries, architecture decision records (ADRs)

## Usage

Point the agent at a file, directory, or specific symbol and describe what documentation you need. Examples of valid requests:

- "Add Google-style docstrings to every public function in `src/services/`."
- "Generate a README for this project based on its structure and package.json."
- "Document this class with JSDoc, including examples for each method."

The agent will respect existing documentation style in the project. If no convention is detected, it will ask which format to use or default to the most common style for the language.

## Examples

### Example 1 — Documenting a Python Class with Google-Style Docstrings

**User Request**: "Add docstrings to this class and its methods."

**Before**:
```python
class TokenBucket:
    def __init__(self, capacity, refill_rate):
        self.capacity = capacity
        self.tokens = capacity
        self.refill_rate = refill_rate
        self._last_refill = time.monotonic()

    def consume(self, tokens=1):
        self._refill()
        if self.tokens >= tokens:
            self.tokens -= tokens
            return True
        return False

    def _refill(self):
        now = time.monotonic()
        elapsed = now - self._last_refill
        self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)
        self._last_refill = now
```

**After**:
```python
class TokenBucket:
    """A token-bucket rate limiter.

    Tokens are added at a constant rate and consumed by callers.
    When the bucket is empty, requests are rejected until enough
    tokens have accumulated.

    Args:
        capacity: Maximum number of tokens the bucket can hold.
        refill_rate: Tokens added per second.

    Example:
        >>> bucket = TokenBucket(capacity=10, refill_rate=2)
        >>> bucket.consume(3)
        True
    """

    def __init__(self, capacity: float, refill_rate: float) -> None:
        self.capacity = capacity
        self.tokens = capacity
        self.refill_rate = refill_rate
        self._last_refill = time.monotonic()

    def consume(self, tokens: int = 1) -> bool:
        """Attempt to consume tokens from the bucket.

        Triggers an internal refill based on elapsed time before
        checking availability.

        Args:
            tokens: Number of tokens to consume. Defaults to 1.

        Returns:
            True if the tokens were available and consumed, False otherwise.
        """
        self._refill()
        if self.tokens >= tokens:
            self.tokens -= tokens
            return True
        return False

    def _refill(self) -> None:
        """Refill the bucket based on time elapsed since the last refill."""
        now = time.monotonic()
        elapsed = now - self._last_refill
        self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)
        self._last_refill = now
```

### Example 2 — Generating a Project README from Structure

**User Request**: "Generate a README for this project."

Given a project with the following layout:
```
myapi/
├── package.json          (name: @acme/myapi, scripts: dev, build, test)
├── src/
│   ├── index.ts          (Express app entry point)
│   ├── routes/
│   │   ├── users.ts
│   │   └── orders.ts
│   └── middleware/
│       └── auth.ts
├── tests/
│   └── users.test.ts
└── Dockerfile
```

**Generated README.md**:
```markdown
# @acme/myapi

A RESTful API service built with Express and TypeScript.

## Getting Started

### Prerequisites

- Node.js >= 18
- npm or yarn

### Installation

git clone https://github.com/a