https://user‑images.githubusercontent.com/6 403 910/227 589 893-a1c47 996-df5a-4d37–83a8–65bd5c515 912.mov

DoccGPT — это эксперимент по полной автоматизации документирования кодовой базы на Swift. Он еще не закончен, но — будет (FAQ читайте ниже).

Работает он с использованием OpenAI и DocC, компилятора документации от Apple:

Компилятор документации DocC преобразует текст на основе Markdown в обширную документацию для проектов Swift и Objective‑C и отображает ее прямо в окне документации Xcode. Вы также можете размещать эту документацию на веб‑сайте.

Совмещая DoccGPT с Swift Package Index (который компилирует и размещает вашу документацию за вас), вы можете приблизиться к полностью самодокументируемой кодовой базе. DoccGPT пишет разметку за вас, или по крайней мере делает первый проход, а Swift Package Index вместо вас заботится о компиляции и размещении сгенерированной документации.

Почти вся разметка в /Sources была сгенерирована при запуске DoccGPT на себе:

В зависимости от используемой модификации OpenAI, DoccGPT достаточно умен для документирования длинного и сложного кода на Swift. При увеличении объема кода, кажется, что более простые модификации справляются сложнее.

Базовое (*элементарное) использование

Запустите исполняемый файл и укажите ему директорию, а также ваш секретный ключ OpenAI.

Внимание: DoccGPT попытается переписать содержимое каждого .swift файла в директории, которую вы ему дали. И если вы дадите ему достаточно большой файл, он не дойдет до конца!

swift run docc-gpt  [--model ] [--context-length ] --key  [--log-level ] [--skip-files ]
ARGUMENTS:

               The folder whose contents you want to document

OPTIONS:

  -m, --model      The OpenAI model to run (default: gpt-3.5-turbo)

  --context-length 

                          The context length corresponding to the OpenAI model chosen (default: 4096)

  -k, --key          Your secret API key for OpenAI

  -l, --log-level 

                          The desired log level (default: info)

  --skip-files 

                          Whether or not files that are too long to documented should be skipped (default: true)

  -h, --help              Show help information.

Как это работает

DoccGPT — это инструмент командной строки, написанный на Swift, который перебирает все файлы.swift в заданной директории и пытается задокументировать ваш код, используя синтаксис DocC:

Синтаксис DocC — так называемая разметка документации — является настраиваемым вариантом Markdown, который добавляет функциональность для параметров, специфичных для документации разработчика, таких как связывание символов, списки определений терминов, списки кода и комментарии.

На момент написания этой статьи, разметка документации создается путем подачи целых файлов.swift в /v1/chat/completions. Я не заметил никакой существенной разницы в производительности между gpt-3.5-turbo и gpt-4. Подача целых файлов может показаться чем‑то наивным, но это приводит к довольно впечатляющему поведению — я удивился, насколько специфичными являются некоторые комментарии в /Sources и то, как модификации производят впечатление «читающих» весь файл, прежде чем добавлять комментарии.

FAQ

Чего не хватает?

Наибольшей проблемой является контекстное окно текущих доступных моделей. Даже с GPT-4 я не смог полностью задокументировать DoccGPTRunner.swift, т.к. у меня закончились токены. Текущие ограничения токенов на момент написания статьи не подходят для того, что я называю средним файлом Swift. Полагаю, в настоящее время решением будет являться написание меньшего количества кода в одном файле или ожидание GPT-5 ?

Я также не придумал, что делать, если нужно перезапустить модификацию для уже задокументированного файла. При работе с более сложным кодом модификации будут принимать решения, отличающиеся от принятых ранее. Второй проход по коду, который уже был прок��мментирован, довольно часто приводит к ужасным изменениям. Возможно, самое главное - я также не придумал, как заставить его повторно задокументировать код при изменении функциональности. Однако все это, вероятно, может быть исправлено с помощью лучшего пайплайна или лучшей модели.

Наконец, требуется выполнить еще много базовой работы в командной строке, чтобы довести это до рабочего состояния, например, обеспечить возможность игнорировать определенные файлы/подкаталоги. Запуск на больших каталогах параллельно также может привести к ограничению скорости - обходной путь уже разрабатывается.

Буду ли я использовать его в продакшене?

У меня нет сведений о проблемах конфиденциальности при отправке всей кодовой базы на серверы OpenAI, но лишь по одной только этой причине я, в��роятно, не использовал бы его.

Но если предположить, что мы учтем описанные выше проблемы конфиденциальности и ограничений? Скорее всего, я бы избегал авто-коммитов через CI, хотя и кажется, что при самом первом запуске эти модификации очень хороши в документировании кода в детерминированном и высококачественном виде.

Тем не менее, я не считаю надуманным ожидание полностью автоматизированных самодокументируемых кодовых баз в ближайшем будущем. Мое первое впечатление - хорошая подсказка имеет большое значение, и что есть огромные различия в производительности между различными моделями/API. Я буду рад будущему, где мы сможем запускать мощные модификации с большими контекстными окнами локально.

One more thing…

Любознательный читатель может заметить, что некоторые примеры документации, используемые в подсказке, взяты из неподражаемого NSHipster. Я давний фанат и огромный ценитель всего, что NSHipster сделал для мобильных разработчиков повсюду.