Docstrings and Doc Comments skill for Codex

A doc comment is worth its lines when a caller can use the function correctly without reading its body: what it does, what each argument means beyond its type, what comes back, what can go wrong, and anything surprising. A doc comment that repeats the name and types is noise; a wrong one is a bug.

Inspect first

cat AGENTS.md 2>/dev/null | head -60
rg -n "convention|pydocstyle|\"D\"|interrogate" pyproject.toml setup.cfg ruff.toml 2>/dev/null
rg -n "jsdoc|tsdoc|typedoc" package.json eslint.config.* typedoc.json 2>/dev/null
rg -n "missing_docs|missing_errors_doc" --glob '*.rs' --glob 'Cargo.toml' 2>/dev/null | head

Then read five existing well-documented functions in the codebase. Match their style (Google vs NumPy, sentence case, tense, whether types are repeated) exactly. Consistency with the repo beats any external guide.

What to document, in priority order

Priority	Target	Reason
1	Public API of a library (exported, __all__, pub, export)	Users cannot read your source
2	Functions with non-obvious behaviour: side effects, I/O, mutation, caching, retries	Callers get these wrong
3	Anything that raises or returns errors callers must handle	Error contract is invisible in the signature
4	Module and package level docs	Orientation for new readers
5	Private helpers whose name and types already say everything	Usually skip

Content of a good doc comment

1. Summary line: one sentence, what it does, from the caller’s view. Imperative or third person per house style (“Return the…” in Python PEP 257; “Returns the…” in Javadoc/TSDoc tradition). Under ~80 characters.
2. Details (optional): behaviour the caller must know, such as ordering, idempotency, complexity for large inputs, thread safety, units, time zones.
3. Parameters: meaning, units, valid range, what None/null/empty means. Do not repeat a type the signature already declares unless the convention requires it.
4. Returns: what and in which cases; what an empty result means.
5. Errors: each exception or error variant and the condition that causes it.
6. Example: for public functions whose usage is not obvious; make it runnable as a doctest where the language supports it.
7. Deprecation with replacement and removal version, when relevant.

Never document implementation details that may change (“uses a dict internally”) unless callers depend on them; those belong in code comments ($code-comments).

Python

Google style (most common default; set the convention in ruff):

def charge(customer_id: str, amount: int, *, currency: str = "usd", idempotency_key: str | None = None) -> Charge:
    """Charge a customer's default payment method.

    The call is safe to retry when ``idempotency_key`` is given: a repeated key returns
    the original charge instead of creating a new one.

    Args:
        customer_id: Processor customer ID, e.g. ``"cus_9Qx2"``.
        amount: Amount in the smallest currency unit (cents for USD). Must be positive.
        currency: ISO 4217 code, lowercase.
        idempotency_key: Unique key per logical charge; keys expire after 24 hours.

    Returns:
        The created charge. ``status`` is ``"pending"`` until the processor confirms.

    Raises:
        CardDeclinedError: The issuer declined the payment.
        ValueError: ``amount`` is zero or negative.

    Example:
        >>> charge("cus_test", 500).amount
        500
    """

NumPy style uses underlined section headers (Parameters, Returns, Raises) and suits scientific code with array shapes; reST/Sphinx style uses :param x: fields. Pick what the repo uses; do not mix styles in one package.

# pyproject.toml
[tool.ruff.lint]
extend-select = ["D"]
[tool.ruff.lint.pydocstyle]
convention = "google"          # or "numpy", "pep257"
[tool.ruff.lint.per-file-ignores]
"tests/**" = ["D"]

ruff check --select D src/
interrogate -v --fail-under 80 src/      # docstring coverage; pip install interrogate
pytest --doctest-modules src/            # runs >>> examples

TypeScript and JavaScript

TSDoc for TypeScript (types come from the signature, so no {type} in tags):

/**
 * Charges a customer's default payment method.
 *
 * @remarks
 * Safe to retry when `idempotencyKey` is set: a repeated key returns the original charge.
 *
 * @param customerId - Processor customer ID, for example `cus_9Qx2`.
 * @param amount - Amount in the smallest currency unit (cents for USD). Must be positive.
 * @returns The created charge; `status` is `pending` until the processor confirms.
 * @throws {@link CardDeclinedError} When the issuer declines the payment.
 *
 * @example
 * ```ts
 * const c = await charge("cus_9Qx2", 500, { idempotencyKey: orderId });
 * ```
 */
export async function charge(customerId: string, amount: number, opts: ChargeOptions = {}): Promise<Charge> {

Plain JavaScript uses JSDoc with types in braces: @param {number} amount - ..., and those types feed editor tooling and tsc --checkJs.

// eslint.config.js (flat config)
import jsdoc from "eslint-plugin-jsdoc";
export default [
  jsdoc.configs["flat/recommended-typescript"],   // or "flat/recommended" for JS
  { rules: { "jsdoc/require-jsdoc": ["warn", { publicOnly: true }] } },
];

For TSDoc syntax validation add eslint-plugin-tsdoc (tsdoc/syntax). For generated API docs, TypeDoc with "validation": { "notDocumented": true } in typedoc.json warns about undocumented exports; add "treatWarningsAsErrors": true in CI.

Go

// Charge charges the customer's default payment method and returns the created charge.
// Amount is in the smallest currency unit. Charge is safe to retry when key is non-empty.
//
// It returns ErrCardDeclined when the issuer declines the payment.
func Charge(ctx context.Context, customerID string, amount int64, key string) (*ChargeResult, error) {

• Begin with the identifier’s name; full sentences; package comment starts // Package billing ... in one file (often doc.go).
• Doc comments support headings (# Title), lists and links ([ErrCardDeclined], [context.Context]); gofmt normalises them.
• Check with go doc ./billing Charge; revive’s exported rule flags missing comments.

Rust

/// Charges the customer's default payment method.
///
/// # Errors
///
/// Returns [`ChargeError::Declined`] when the issuer declines the payment.
///
/// # Examples
///
/// ```
/// # use billing::charge;
/// let c = charge("cus_test", 500)?;
/// assert_eq!(c.amount, 500);
/// # Ok::<(), billing::ChargeError>(())
/// ```
pub fn charge(customer_id: &str, amount: u64) -> Result<Charge, ChargeError> {

Conventional sections: # Examples, # Errors, # Panics, # Safety (required for unsafe fn). Enforce with #![warn(missing_docs)] in lib.rs, clippy’s missing_errors_doc and missing_panics_doc (pedantic group), and run examples with cargo test --doc. Build with cargo doc --no-deps and fix broken intra-doc links.

Java

Javadoc with @param, @return, @throws, {@code ...} and {@link ...}; run javadoc -Xdoclint:all or the build’s doclint to catch missing tags. JDK 23+ also accepts Markdown doc comments with /// (JEP 467); use them only if the project targets 23+ and already chose that style.

Bulk generation workflow

- [ ] 1. Measure coverage (interrogate, TypeDoc validation, missing_docs) and list targets
- [ ] 2. Start with public API, sorted by usage (rg call counts) or by module
- [ ] 3. For each function: read the body AND its tests; note errors, side effects, units
- [ ] 4. Write the doc comment; add an example if usage is non-obvious
- [ ] 5. Flag mismatches between code and existing docs as findings, do not silently pick one
- [ ] 6. Run linter, doctests, doc build; re-measure coverage

Work in reviewable batches (one module per commit). Generated docstrings that merely paraphrase names (“Gets the user. Args: user_id: The user id.”) fail review; if the honest content is that thin, skip the function or document only its error cases.

Gotchas

• Docstring says “returns None if not found” but code raises. Read the body every time.
• Units and time zones missing: “timeout” in seconds or milliseconds? “date” in UTC?
• Copy-pasted docs from an overload or sibling function with different behaviour.
• Python: a string literal placed after any other statement in the body (an import, an assignment) is not a docstring; help() and doc tools ignore it. It must come first.
• TSDoc @param name - description requires the hyphen; JSDoc style {type} inside TS files duplicates and can contradict the real types.
• Doctest examples that depend on network, time or random output; seed or mark them skipped (# doctest: +SKIP, ```no_run in Rust).

Verification

• Linter clean for the docstring rules; coverage at or above the agreed threshold.
• Doctests pass (pytest --doctest-modules, cargo test --doc).
• Doc build has no warnings (cargo doc, TypeDoc, Sphinx -W).
• Spot-check five generated docstrings against code and tests: every stated error, default and unit is correct.

Report

**Scope:** src/billing (public API, 34 functions)
**Coverage:** interrogate 41% -> 92%; remaining are private helpers
**Style:** Google (matches existing), ruff D rules enabled with google convention
**Doctests:** 11 added, all passing
**Code/doc mismatches found:** 2 (refund() raises on partial refunds; docs said it clamps), not changed, needs owner decision