I Automated Python Docstrings for a Month — The Workflow That Finally Stuck

Here is a confession most Python developers recognise: I have never kept docstrings current by willpower alone. Not once, across a full project. The deadline lands, the function works, and the docstring becomes "one line for now" — then two months later it describes the previous signature, which is worse than no docstring at all, because readers trust it.

So last month I stopped writing docstrings by hand entirely and ran two very different things in their place: a ~40-line stdlib audit script, and dedicated AI doc tools. Then I had a separate AI model grade the output blind. This is what survived, what broke, and the loop I still have running today.

What the standard library gives you for free

Before paying anyone anything, know how far the stdlib gets you. Two modules do most of the work.

inspect — runtime introspection:

import inspect
from mymodule import api

for name, fn in inspect.getmembers(api, inspect.isfunction):
    if not inspect.getdoc(fn):
        print(f"missing docstring: {name}")

This runs against imported modules, so it sees exactly what a user of your library sees. Ten lines, zero dependencies. The catch: the module must import cleanly, and dynamic functions (decorators that rebuild signatures, __getattr__ tricks) can fool it.

ast — static auditing without importing:

import ast, sys

tree = ast.parse(open(sys.argv[1]).read())
for node in ast.walk(tree):
    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
        if ast.get_docstring(node) is None:
            print(f"{sys.argv[1]}:{node.lineno} {node.name} lacks a docstring")

Forty lines gets you a coverage report across an entire tree — how many public functions are documented, which modules regressed since last week. Feed it to CI and you have a hard gate. Tools like interrogate and docstr-coverage are polished versions of the same idea, and they are genuinely good.

Where the stdlib stops: both approaches answer one question — is there a docstring? — and neither answers the question that actually matters: is the docstring true? Detection is a solved problem. Authoring and verification are not.

Stdlib script vs. dedicated AI doc tools

Dimension	stdlib ast/inspect script	Dedicated AI doc tool
Finds missing docstrings	Excellent — free, instant	Usually yes, bundled in
Writes new docstrings	Not at all	Yes — the whole point
Detects stale/wrong docstrings	No	Yes, if it compares signature to prose
Cost	$0 + maintenance time	One-time or subscription
Data leaving your machine	Never	Depends on the tool — read its policy
Works in CI as a gate	Trivially	Usually, via CLI
Output quality	Whatever you write	Surprisingly good, occasionally hallucinated

The pattern in that table is why this stopped being either/or for me: the stdlib script is your measuring stick, the AI tool is your worker. Use the first to define "done" and the second to get there.

How the blind grading actually went

My test setup: a ~4,000-line personal project, roughly 60% documented. I ran a stdlib coverage audit for the baseline, let three tools generate docstrings for the undocumented remainder, then gave a separate AI model twenty randomly chosen docstrings — mixed sources, mixed with my own hand-written ones — and asked it to score each on accuracy, specificity, and usefulness (1–5), without telling it the origin.

Results that surprised me:

• My hand-written docstrings did not win. Three of the five lowest-scoring entries were mine — vague on edge cases, silent about return types, one outright wrong about a None path.
• AI docstrings were specific to the point of being pedantic. They documented exception paths and None returns I had never mentioned. That is exactly what a reader needs at 2 a.m.
• One hallucination. A generator invented a keyword argument that does not exist. This is why a human pass — or a doctest run — is non-negotiable. Auto-merge and you are shipping fiction.

The tool that ended up in my workflow

Of the tools I tested, the one that stayed was AI Doc Generator, because it does the unglamorous half of the job: it scans the codebase, reports docstring coverage, and generates Google-style docstrings for what is missing — so the audit step and the authoring step live in one place instead of my homegrown script plus a separate generator.

Disclosure: AI Doc Generator is our own tool, and the link below is an affiliate link — we earn a commission at no extra cost to you. It is $49 one-time, no subscription. Check it out here.

The coverage report alone paid for the thing, because it turned "I should document more" into a number that went down every run. The generated docstrings still needed a review pass — the hallucinated-argument problem above is real — but reviewing is dramatically faster than writing from a blank line. On dense utility modules it was excellent; on heavy metaclass magic it produced confident nonsense and I reverted those by hand.

The loop that actually sticks

1. Audit — stdlib script or the tool's coverage report, run on every PR. Number goes up or the PR waits.
2. Generate — AI fills the gaps for anything the audit flags.
3. Verify — human skim plus a doctest or two on the functions you care about most. Non-negotiable.
4. Explain why — if you use AI coding agents alongside this, they follow rules better when the rules are written down in checked-in files.

Most of the prompt-engineering effort here is unglamorous: telling the generator what style, what audience, and how much detail. If you have not learned to write instructions that survive contact with an LLM, learn that first — the same principles apply to docstring prompts.

Who this is NOT for

• Security-cleared or air-gapped codebases. If your code cannot leave the machine, lean on the stdlib audit + human writing. The measuring stick is safe; the worker may not be.
• Codebases under ~500 lines. You can hand-write everything. The automation overhead exceeds the pain.
• Heavily dynamic or metaprogrammed code. Generators hallucinate signature details exactly where introspection is hardest. Expect to revert a lot.
• Teams with no review culture. If nobody reviews anything, auto-generated docs become confident fiction with a nice format. Fix the review habit first.
• Documentation that is really prose. Design docs, ADRs, tutorials — an LLM will produce text, not understanding. This is about API reference hygiene.

Honest verdict

Stop writing docstrings by hand — but do not stop caring whether they are true. The stdlib gives you a free, excellent auditor and zero authors. AI doc tools give you an author that is usually right and occasionally confidently wrong. The combination — audit with a script, generate with a tool, verify with a human and a doctest — is the first docstring workflow I have kept running past week two.

---

Originally published at AI Stack Lab — hands-on AI tool tests and workflows.