􀉪🧹 Самодокументируемый код на Swift с помощью GPT и DocC

     📝  Написано Гонзало Нуньесом и еще 1 участником.

􀐬 🕓 Разработка длилась 11 дней, сделано 67 коммитов и 5 релизов.

􀌥  💬 Существует 2 открытых вопроса и нет открытых пул-реквестов. Последний вопрос был закрыт 2 дня назад и последний пул-реквест был объединен/закрыт 2 дня назад.

• Этот пакет зависит от 2 других пакетов. 
• Лицензировано MIT.
• 96 звезд
• 1 библиотека
• 1 исполняемый файл
•  Нет плагинов.

https://user-images.githubusercontent.com/6403910/227589893-a1c47996-df5a-4d37-83a8-65bd5c515912.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 ]

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

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 сделал для мобильных разработчиков повсюду.