Auto-generated docstrings are useless: they restate the function signature in English. def add(a, b): """Adds a and b.""". Thanks.
I wrote a prompt that reads the function body and forces it to document the non-obvious stuff: what the caller must know, the edge cases, the reason it exists. It refuses to state anything already obvious from the name and types.
Still working out how to make it flag when a function is doing too much to document cleanly.
Write a docstring for the function below. The docstring must NOT restate what is already obvious from the name and type hints. Instead, include only: - One line: what this does and, critically, WHY it exists / when a caller reaches for it. - Any non-obvious precondition the caller must satisfy (state that isn't in the signature, ordering, side effects). - Edge cases and what happens at them (empty input, None, boundary values) that a reader couldn't infer. - What it raises and under what condition. If the function's behavior is fully obvious from its signature (a pure trivial helper), output a single-line docstring and say nothing more. If you find the function is doing several unrelated things and can't be documented as one coherent unit, prepend a comment '# NOTE: consider splitting -' explaining why. Match the surrounding docstring style (Google / NumPy / reST) if you can detect it.
The 'consider splitting' flag turned my docstring pass into a low-key refactoring signal, which I did not expect but now rely on. If the model struggles to describe the function in one coherent WHY, that's usually the function's problem, not the model's.