УДК 004

Обзор средств автоматического формирования документации по программному коду

Катаев Георгий Николаевич - студент факультета Робототехники и Комплексной Автоматизации Московского Государственного Технического Университета Им. Н.Э. Баумана.

Научный руководитель: Кузьмина Инна Анатольевна - кандидат технических наук, доцент факультета Робототехники и Комплексной Автоматизации Московского Государственного Технического Университета Им. Н.Э. Баумана.

Аннотация: Статья посвящена сравнению инструментов автоматического форматирования документации по программному коду. Приводятся основные средства составления документации Doxygen, Sphinx, Swagger.

Ключевые слова: документация, автоматизация, разбор кода, языки программирования.

Введение

В индустрии разработки программного обеспечения создание документации является неотъемлемой частью любого проекта. Увеличение сложности разрабатываемых программных продуктов приводит к увеличению объема документации и предъявлению новых требований к ее содержанию. Сейчас автоматическое формирование документации становится неотъемлемой частью крупных проектов, улучшая качество и сокращая сроки разработки документации.

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

В статье представлен обзор современных инструментов автоматического формирования документации – Doxygen, Sphinx, Swagger. Цель статьи – познакомить читателя с данным инструментами, рассмотреть их преимущества и недостатки, тенденции и перспективы развития.

Теоретические основы автоматического формирования документации

Автоматическое формирование документации по программному коду – это процесс, при котором документация создается из исходного кода программы без участия человека. Этот процесс опирается на тщательный анализ кода, включая изучение встроенных комментариев и аннотаций, что обеспечивает создание всесторонних технических документаций, инструкций для пользователей и описаний API.

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

Разбор кода позволяет идентифицировать структурные элементы программы, такие как функции, классы и методы. Данный этап критически важен для понимания структуры и логики программы. Анализ зависимостей выявляет как явные, так и неочевидные связи между различными компонентами кода. Это позволяет составить полную картину взаимодействия элементов программы между собой. Интерпретация комментариев и аннотаций дает возможность извлекать описательную информацию. Это делает документацию понятной и информативной.

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

Ключевые инструменты автоматического формирования документации

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

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

Doxygen, разработанный Дмитрием ван Хеушем в 1997 году, стал одним из первых продуктов в области автоматической генерации документации из исходного кода. Этот инструмент поддерживает множество языков программирования, включая C++, Java, Objective-C, и Python, что делает его универсальным решением для многих проектов [1].

Интерфейс Doxygen, основанный на командной строке, предлагает гибкость в настройке параметров генерации документации. Среди его мощных возможностей – автоматическое создание диаграмм классов и диаграмм взаимодействия компонентов, что облегчает понимание архитектуры проекта. Эти диаграммы, сгенерированные Doxygen, обеспечивают визуальное представление зависимостей и иерархии внутри кода, способствуя более глубокому анализу структуры программного обеспечения. Интерфейс Doxygen представлен на рисунке 1. На рисунке 2 представлен прямой граф, который иллюстрирует цепочку зависимостей файлов программы, вплоть до документируемого файла [2].

Рисунок 1. Интерфейс Doxygen.

Рисунок 2. Прямой граф зависимостей.

Sphinx, созданный Георгом Брандлом в 2008 году как часть проекта Python, быстро вырос в профессиональный инструмент для создания обширной и качественной документации. Основываясь на разметке ReStructuredText, Sphinx обеспечивает создание логически структурированной и визуально привлекательной документации, поддерживающей экспорт в несколько форматов, включая HTML и PDF. Его система расширений позволяет интегрировать дополнительные функции, такие как автоматическое создание индексов и кросс-ссылок, что делает Sphinx особенно ценным для создания обширных документаций в академическом и техническом контексте [3].

Sphinx является пакетом для языка Python, поэтому не имеет как такого интерфейса. Работа с ним ведётся с помощью команд, которые вводятся в терминал. Чтобы начать работу необходимо создать и перейти в новую директорию и находясь в этой директории запустить команду «sphinx-quickstart», вследствие чего запустится процесс, результатом которого будет файл conf.py [4]. Пример такого файла изображен на рисунке 3.

Рисунок 3. Пример сгенерированного conf.py с помощью Sphinx.

Swagger (OpenAPI), разработанный SmartBear Software, выделяется своей специализацией на описании и документировании RESTful API. С помощью Swagger разработчики могут легко создавать детализированные спецификации своих API, которые затем используются для генерации интерактивной документации. Эта документация предоставляет пользователям возможность непосредственно тестировать API из браузера, что упрощает процесс разработки и тестирования веб-сервисов. Интерфейс Swagger UI облегчает взаимодействие с документацией, делая ее доступной и понятной как для разработчиков, так и для конечных пользователей [5].

 Swagger или OpenAPI framework состоит из 4 основных компонентов [6]:

• Swagger Core – позволяет генерировать документацию на основе существующего кода основываясь на Java Annotation.
• Swagger Codegen – позволяет генерировать клиентов для существующей документации.
• Swagger UI – графический интерфейс (рис 4). Он визуализирует документацию, представляет ее в более простом для понимания виде. Компонент позволяет генерировать и направлять различные REST запросы для тестирования API и обеспечивает удобную навигацию по документации
• Swagger Editor – позволяет создавать документацию в YAML или JSON форматах.

Рисунок 4. Интерфейс Swagger.

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

Современные тренды и инновации

Современные тренды и инновации в автоматическом формировании документации направлены на повышение удобства разработки и налаживание более тесной связи с процессами непрерывной интеграции и доставки (CI/CD или же Continuous Integration and Continuous Delivery). Одним из ключевых направлений является использование облачных платформ и сервисов, которые позволяют разработчикам легко документировать программные продукты в реальном времени. Это позволит упростить совместную работу разработчиков и сделает документацию доступной из любой точки мира.

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

Ещё одна значимая тенденция в области автоматической генерации документации – это развитие стандартов и форматов документации, таких как Markdown и reStructuredText. Эти форматы облегчают создание читаемой и структурированной документации и поддерживаются большинством современных инструментов и платформ. Это позволяет упростить переносимость и обмен документацией между различными проектами и командами [7].

Наличие вышеуказанных трендов свидетельствует об актуальности и важности задачи сделать процесс разработки и актуализации документации более эффективным.

Задачи и проблемы, сопровождающие процесс автоматизированной генерации документации при разработке программного обеспечения

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

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

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

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

Заключение

Автоматическое формирование документации играет важную роль в упрощении и оптимизации процесса разработки программного обеспечения. Инструменты, такие как Doxygen, Sphinx и Swagger (OpenAPI), предоставляют эффективные средства для генерации, обновления и поддержке версионности документации, позволяя разработчикам сосредоточиться на разработке и повышении качества продукта. Однако, использование данных инструментов требует выполнения ряда условий к оформлению разрабатываемого кода, таких как обеспечение актуальности и качества комментариев в коде, которые будут использованы инструментами для формирования документации. Для достижения наилучшего результата при автоматическом формировании документации требуется совместная работа команды, грамотный выбор инструментов и постоянное совершенствование процессов разработки.

Список литературы

1. Документация Doxygen / [Электронный ресурс]. - URL: https://www.doxygen.nl/manual/index.html
2. Документируем код эффективно при помощи Doxygen / Habr [Электронный ресурс]. - URL: https://habr.com/ru/articles/252101/
3. Документация Sphinx / [Электронный ресурс]. - URL: https://www.sphinx-doc.org/en/master/index.html
4. Создай, оформи, опубликуй. Sphinx — незаменимый помощник в мире Python документации / [Электронный ресурс]. - URL: https://habr.com/ru/articles/750968/
5. Документация Swagger / [Электронный ресурс]. - URL: https://docs.swagger.io/spec.html