Docstrings that tools and readers can use

Goal

Document public functions, classes and modules in a way that answers the caller's questions and that tooling can extract.

Prerequisites

Type hints on the public interface, so that docstrings describe meaning rather than repeating types.

Steps

1. Follow PEP 257 mechanics: triple double quotes, a one-line summary in the imperative that fits on one line, a blank line, then details.
2. Pick one section style for the project (Google style: Args:, Returns:, Raises:) and configure the linter to check it.
3. Describe what the function does and its contract: preconditions, side effects, errors raised, and any behaviour a caller must know (idempotence, thread safety). Do not narrate the implementation.
4. Document modules with their purpose and the main entry points; document classes with what an instance represents.
5. Skip docstrings for trivial private helpers whose name says everything; noise hides signal.

Expected result

Editors show useful signatures and summaries on hover; generated reference documentation is complete for the public API; reviewers can check behaviour claims against the docstring.

Limits and test basis

Docstrings drift when behaviour changes; review them in the same diff. Examples in docstrings should be executable (doctest) or clearly illustrative. Conventions follow the cited references.