Перейти к содержимому

16. Documentation Writer: README и docstrings

Агентская документация работает, когда сначала извлекается структура кода, а потом пишется текст. Пример показывает именно такой порядок.

По Python-модулю получить README с обзором и примерами или docstrings для функций. Граница: агент описывает то, что видит в коде, и не знает замысла.

flowchart LR
  C["Модуль"] --> X["extract_structure"]
  X -->|"функции, классы, сигнатуры"| G["Генерация"]
  G -->|"--format"| R["README / docstrings"]
  1. extract_structure вытаскивает AST-подобное описание: модуль, классы, функции, сигнатуры.
  2. В зависимости от --format вызывается генератор README или docstrings.
  3. Результат печатается.

Два генератора — generate_readme и add_docstrings — используют одно и то же извлечённое представление.

  • Сначала структура, потом текст. Модель получает сигнатуры, а не весь файл, и меньше придумывает.
  • Один вход — два формата. Извлечение отделено от генерации, поэтому форматы не дублируют логику.
  • Google-style docstrings — конкретный целевой формат, а не «напиши документацию».
  • Описание неверного поведения. Docstring гласит одно, код делает другое.
  • Придуманные примеры. В README появляется вызов с несуществующими параметрами.
  • Нет проверки. Сгенерированные примеры не запускаются.
  • Устаревание. Документация не обновляется при изменении кода.
  • Запускать примеры из README и сверять docstrings с тестами.
  • Обновлять документацию в CI при изменении публичных сигнатур.
  • Хранить docstrings рядом с кодом и проверять линтером на наличие и формат.
  • Для README — генерировать каркас и заполнять смысловые разделы вручную.