write-docstring

Start with a one-line summary of the outcome, then add numpy-style sections only where they add information beyond the signature. Document non-obvious parameters, return semantics, exceptions callers must handle, and any side effects or preconditions.

Numpy-style docstrings use labeled sections like Parameters, Returns, and Raises with dashed underlines. Each parameter is documented with its name, type, and description, making the format readable in plain text and parseable by documentation tools.

No. A class docstring should describe the abstraction the class represents, its responsibilities, invariants, and lifecycle. Constructor parameters belong on the __init__ method docstring, not duplicated at the class level.

A module docstring should state why the file exists and its role in the architecture, optionally naming key public entrypoints or showing how to run a script. It should omit version numbers, provisioning details, and runbook references that go stale.

Skip the Parameters section when the signature and type hints already convey everything, such as obvious names and types with no constraints. Only document parameters with non-obvious meaning, units, ordering, or preconditions.