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

Описание и применение

Автоматизация docstring в Python: сочетание стандартных инструментов для аудита и AI‑генератора для заполнения пробелов, подтверждённая ручной проверкой и doctest‑тестами.

Задача

Python developers struggle to keep docstrings current and accurate, leading to stale or incorrect documentation that misleads readers.

Результат

The combined workflow reduced manual docstring writing, increased coverage, and produced more specific documentation than hand‑written versions, though occasional hallucinations required human review.

Рабочий процесс

• Audit the codebase for missing or stale docstrings using a stdlib script or coverage report.
• Generate missing docstrings with an AI doc generator that outputs Google‑style docstrings.
• Verify the generated docstrings with a human skim and run doctests on critical functions.
• Explain the process and rules to AI coding agents to improve adherence.
• Iterate the loop on every PR, using coverage numbers as a gate.

Доказательства

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 …

Источник

My hand‑written docstrings did not win. Three of the five lowest‑scoring entries were mine …

Источник

One hallucination. A generator invented a keyword argument that does not exist.

Источник