---
name: pydoc
description: 'Write Google-style Python docstrings. Use when: documenting a module, class, function, or method; adding or reviewing pydocs; ensuring docstring completeness and style consistency.'
argument-hint: 'Symbol or file to document (e.g. MyClass, utils.py)'
---

# Python Documentation (Google Style)

## Purpose

Produce concise, accurate Google-style docstrings that describe public behavior without exposing implementation details.

## Writing Style

These rules apply to all prose written inside docstrings:

- Write in US English.
- Do not use em dashes, en dashes, or hyphen sequences (`-`, `--`) as substitutes for dashes in prose. Do not use semicolons to join clauses.
- Avoid filler words and phrases (e.g., "simply", "just", "basically", "it is worth noting"). Be direct.
- Do not use opinionated language, excessive adjectives, or adverbs.
- Never use emojis.
- Do not write self-rebutting statements (e.g., "This works, or at least it should"). Commit to one accurate statement.
- Do not use sensational framing (e.g., "The key insight here is..."). State the information plainly.
- Omit prose that restates what the signature already communicates. Every sentence must add information.

## Docstring Structure (Google Style)

Use the following sections in order, omitting any section that does not apply:

```
Summary line.

Extended description (optional). One or more paragraphs describing observable
behavior, preconditions, and postconditions. Do not describe internal algorithms
or implementation choices.

Args:
    param_name: What the caller must supply and how it affects behavior.
        Use a hanging indent for continuation lines.
    param_name (type): Include the type annotation in parentheses only when the
        signature lacks a type hint.

Returns:
    What the callable produces. Omit for functions that return None.

Yields:
    What each yielded value represents. Use instead of Returns for generators.

Raises:
    ExceptionType: The condition under which this exception is raised.

Note:
    A single short note when a behavioral quirk cannot be expressed concisely
    elsewhere. Omit if not needed.

Example:
    result = my_function(42)
```

## Rules by Symbol Type

### Module

Write one paragraph describing the module's responsibility and its place in the broader system. Do not list every class or function; let the symbol-level docstrings speak for themselves.

### Class

Describe what the class represents and the contract it exposes to callers. Document `__init__` arguments under an `Args:` section in the class docstring, not in a separate `__init__` docstring, unless the class inherits from a base whose `__init__` is separately documented.

### Function / Method

- The summary line must be a sentence fragment starting with a verb in the imperative mood (e.g., "Return...", "Compute...", "Validate...").
- One summary line only. Begin extended description on the line after a blank line.
- Document every parameter, including `self`-adjacent context, except `self` and `cls`.
- Do not restate the parameter name in its description.

### Property

Use a noun phrase as the summary (e.g., "The current connection timeout in seconds."). Omit `Args:` and `Returns:`.

## Conciseness Requirements

- Each `Args:` entry must fit in one to three lines. If more explanation is needed, it belongs in the extended description, not in the argument entry.
- Avoid repeating information already expressed by type hints or default values.
- Do not add `None` as a type annotation in `Args:` when the signature already has `Optional[T]` or `T | None`.
- Do not write `Returns: None` or `Returns: Nothing`.

## What to Omit

- Private methods and attributes (`_name`, `__name__`) do not require docstrings unless they are non-obvious and untested.
- Do not describe algorithmic steps, data structure choices, or internal variable names.
- Do not reference other internal symbols by implementation path (e.g., `self._cache`). Reference only the public API.

## Inheritance and Class Hierarchy

- A docstring must only describe the contract as seen from that class's level in the hierarchy. Do not mention subclasses or sibling classes behaviors or name.
- When a subclass overrides a method, document the refined contract in the override's docstring.
- When a subclass changes an inherited method's contract without overriding it (e.g., by overriding a dependency that the method calls, such as via a subclassed callback used by the parent class), document the changed contract at the class level in the subclass docstring since the subclass will have no method to document the behavior.
- Subclass contracts should narrow inherited contracts, not widen them (Liskov Substitution Principle). If you observe a subclass widening a contract (e.g., accepting more input types or returning a broader type than the base), document it as-is and warning the user directly that the contract diverges from the base class.

## Procedure

1. Identify the symbol to document (module, class, function, or method).
2. Read the public signature and any existing docstring.
3. Draft the summary line using an imperative verb phrase.
4. Add an extended description only if the summary line is insufficient to convey preconditions, postconditions, or non-obvious behavior.
5. Document each parameter under `Args:` in signature order.
6. Add `Returns:`, `Raises:`, and other sections as needed.
7. Review against the writing style rules above. Remove any sentence that restates the signature or describes implementation internals.
8. Verify that no new linter warnings were introduced (e.g., `D` rules from ruff).