Блог UDE (Русский)

Программирование без знания языка: как ИИ уволил Doxygen

Thu, 06 Aug 2026 00:00:00 GMT

В прошлой части мы остановились на том, что выбросили HTML-выдачу Doxygen в мусорное ведро. План «быстро поправить стили» полностью провалился, потому что невозможно адаптировать структуру из вложенных таблиц родом из девяностых под современный дизайн. Идея второго прототипа звучала солидно: отключить генерацию HTML, взять сырой структурированный XML от того же Doxygen и написать для него нормальный парсер.

Рабочим языком, как и в прошлый раз, выбрали Python. Он идеально подходит для создания утилит, обработки текста и автоматизации рутины. К тому же вся современная экосистема вокруг искусственного интеллекта строится именно на нем. Логика была проста: если мы хотим активно использовать нейросети для помощи в написании кода, лучше сразу писать на языке, который они знают лучше всего.

Пришло время раскрыть небольшой секрет, о котором я специально умолчал в первой части: я не знаю Python. Чужой код я плюс-минус понимаю, но сам на нём никогда ничего не писал.

Архитектор, который не умеет кодить

Это был чистый эксперимент в стиле «программирование без знания языка». Я решил выступить в роли системного архитектора и постановщика задач. ИИ должен был выполнять всю техническую работу: писать готовый код, рефакторить функции и собирать всё воедино.

Поначалу всё шло подозрительно гладко. Мы накидывали логику разбора гигантских XML-файлов. Я открывал сгенерированный Doxygen файл, видел там узлы, классы, параметры методов, и просто писал в чат: «Найди все элементы с нужными тегами, вытащи оттуда тип, имя и описание, а затем сложи это в JSON». Благодаря прямому доступу ИИ к терминалу мне даже не пришлось копировать код руками. Нейросеть сама писала скрипты, сразу их запускала и выдавала готовый результат.

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

Когда ИИ внезапно попросил компилятор

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

ИИ выдал будничный ответ: «Конечно, проблем не возникнет. Только для полной переносимости нам потребуется настроить скачивание clang в процессе инсталляции пакета».

Я смотрел на монитор в полном недоумении. Какой ещё clang? Мы разбираем XML-документацию для Python-обертки. При чём здесь компилятор языка C? Я так прямо и спросил у нейросети, не сошла ли она с ума.

ИИ тут же извинился и выдал новую формулировку: «Прошу прощения, я имел в виду библиотеку tree-sitter. Нам понадобится компилировать её биндинги».

Инсайт из потери контроля

И тут до меня дошло: ИИ больше не парсил XML от Doxygen. Ему это надоело.

В процессе наших долгих обсуждений архитектуры нейросеть незаметно для меня подключила парсер абстрактных синтаксических деревьев (AST). ИИ сам решил, что читать оригинальный исходный код C++ и Python напрямую через tree-sitter гораздо надёжнее, чем возиться с костыльной XML-выдачей сторонней утилиты. Он просто исключил Doxygen из цепочки, пока я думал, что мы всё ещё парсим теги.

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

Проблема заключалась в абсолютной потере контроля. Если ИИ в фоновом режиме втихую меняет архитектуру и тянет за собой тяжелые библиотеки парсинга, а ты даже не можешь прочитать его код — проект обречён. Получается классический «черный ящик». Любой минорный баг заставит тебя часами выпытывать у нейросети причины поломки. То же самое касается и нетипичных комментариев в исходниках.

Этот инцидент подарил нам важнейшее открытие. Мы поняли, что ИИ действительно способен писать собственные прямые парсеры для любых языков программирования, вытаскивая структуру классов и параметры прямо из живого кода. Нам больше не нужны сторонние утилиты.

Однако, чтобы такой сгенерированный код работал стабильно, его необходимо жёстко контролировать. Нам требовался строгий набор автоматических проверок. Такая система, которая гарантировала бы работоспособность парсера независимо от того, понимаю я написанный код или нет.

Так мы выкинули наш второй, вполне рабочий прототип в корзину. И начали всё заново, уже в третий раз. Но теперь по совершенно другим правилам — с тестированием на каждом шагу. Об этом я расскажу в следующей части.

Также читайте нас:

Как не надо строить документацию: история одного парсера HTML

Mon, 03 Aug 2026 00:00:00 GMT

Мы сели писать собственный движок документации от безысходности. Изначально никто не планировал разрабатывать масштабный UDE. У нас была простая утилитарная задача — задокументировать свежую обёртку на Python. Как обычно, самые монструозные костыли начинаются с безобидных скриптов на пару строк.

Внезапный Python

Наш основной SDK написан на C++. Чтобы им можно было пользоваться из других языков, создаются обертки. Дошла очередь до Python. Разработчики выдали готовый API, который теперь нужно было публиковать на портале документации.

Мы давно сидели на Doc-o-Matic. Старый, тяжелый, проверенный временем генератор. Одно плохо: код на Python он категорически не понимал. Программа годами не обновлялась, техподдержка давно умерла, поэтому рассчитывать на патчи не приходилось. У нас есть жесткие корпоративные требования к дизайну портала. Ни один из стандартных генераторов им не соответствовал, а задокументировать код было необходимо.

Мы посмотрели в сторону Doxygen. Утилита вытаскивает структуру из чего угодно. Правда стандартный HTML на выходе выглядит как привет из девяностых. Тут-то нам в голову и пришла гениальная мысль.

«Мы просто немного причешем стили»

«Doxygen генерирует готовые страницы. Давайте натравим скрипт, подменим пару CSS, и всё будет готово за пару дней».

Оказалось, мы катастрофически недооценили масштаб проблемы. План был прост: перехватить выдачу, подсунуть в свою структуру и пойти пить кофе. Но чем глубже мы лезли в сгенерированный DOM, тем хуже становилось. Doxygen абсолютно игнорировал современные подходы к верстке (вместо понятных тегов мы разгребали завалы таблиц и инлайн-стилей).

Отступать было поздно. Прототип требовался уже вчера, поэтому пришлось стиснуть зубы и дописывать скрипт. Постепенно он обрастал десятками регулярных выражений, становясь всё более хрупким.

Боковое меню и JS-некромантия

Самое дикое началось на этапе навигации. У нас в компании строгое правило UI: абсолютно все страницы должны лежать в левом боковом меню (чтобы разработчик видел всю картину). Doxygen с этим подходом не согласен. Он строит меню динамически из глубоко вложенных массивов, размазанных по нескольким сгенерированным файлам JavaScript.

Нам с ИИ пришлось физически вычитывать эти JS-файлы как обычный текст. Мы парсили массивы, вытаскивали оттуда иерархию классов и руками перестраивали HTML-дерево страницы. Это уже походило на цифровую некромантию.

Семь раз отмерь, один раз распарси

Прототип в итоге завелся. Снаружи всё выглядело прилично и по стандартам. Но внутри же наш скрипт представлял собой карточный домик на изоленте. Выходит минорный апдейт Doxygen — и весь портал рассыпается с ошибками.

Мы потратили уйму времени на попытку срезать угол. Вместо этого можно было спокойно продумать нормальную архитектуру и реализовать ее. Нам стоило сразу вытаскивать абстрактное синтаксическое дерево, или хотя бы просто парсить чистый XML от Doxygen.

Стало очевидно: нужен свой независимый движок. Мы снова подключили ИИ, чтобы он по-быстрому накидал нормальный парсер для чтения XML от Doxygen. Но и тут всё пошло не так. О том, что бывает, когда оставляешь ИИ без присмотра, расскажу в следующей части.

Также читайте нас:

UDE: От исходного кода к качественной документации

Wed, 22 Jul 2026 00:00:00 GMT

1. Отправная точка: исходный код и комментарии

Основа любой качественной API-документации — это комментарии в исходном коде. В больших проектах (например, на C++) они являются единым источником истины. Без них автоматическая генерация документации попросту невозможна.

Вопрос лишь в том, как превратить эти комментарии в современный, удобный и быстрый сайт для разработчиков.

2. Как это решается сегодня — и где система ломается

Самый популярный инструмент для C++ — это Doxygen. Однако его родной формат вывода (HTML или XML) не подходит для современных генераторов статических сайтов (SSG), таких как Hugo, Docusaurus или VitePress, которые ожидают на входе Markdown.

Связка Doxygen + DoxyBook2 + Hugo

Чтобы обойти это ограничение, часто используют промежуточные конвертеры: Doxygen генерирует XML → DoxyBook2 конвертирует XML в Markdown → Hugo собирает сайт.

Это рабочий вариант, но у него есть серьезные ограничения:

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

3. Решение от UDE: единый конвейер

UDE полностью перестраивает процесс, убирая лишние этапы конвертации и оптимизируя работу с данными.

Архитектура UDE строится на четком разделении этапов:

Collector извлекает данные напрямую из исходного кода.
Parser переводит их в нормализованную языково-нейтральную модель — IR (Intermediate Representation).
Renderer мгновенно собирает Markdown/HTML в формате, который понимает целевой SSG, без всяких промежуточных XML-костылей.

Преимущества такого подхода очевидны: нет лишнего шага конвертации, а из единой точки (IR) можно рендерить документацию в любых нужных форматах и стилях.

4. Скорость и предсказуемость

Для больших проектов критически важно время сборки. В UDE эта проблема решается с помощью инкрементального кэширования.

Вместо загрузки всего графа сущностей каждый раз, UDE пересчитывает только то, что реально изменилось.

Кросс-платформенность. Пайплайн работает абсолютно идентично локально на Windows и в CI на Linux.
Doc-as-code. Конфигурация того, что документировать, версионируется вместе с кодом и собирается в том же CI.

5. UDE и ручные руководства (DevGuide)

API-справочник, сгенерированный из кода, отвечает на вопрос «как устроены функции и классы». Но он не может рассказать, «в каком порядке их вызывать для решения конкретной бизнес-задачи». Для этого нужны DevGuide — написанные вручную статьи и туториалы.

UDE не пытается заменить этот ручной труд. Вместо этого он обеспечивает идеальную интеграцию: генерируемый API-справочник остается полным и всегда актуальным, органично соседствуя с ручными гайдами на страницах современных SSG.

Также читайте нас: