Doxygen Documentation

Содержание

• Введение
• Принципы документирования кода
• Конфигурирование Doxygen
• GUI: программа Doxywizard
• Результаты работы и форматы вывода
• Ошибки компиляции документации
• Дополнительно

---

Введение

Doxygen — это утилита для автоматической генерации документации на основе исходного кода. Она полезна тем, что ускоряет процесс аннотирования проекта и позволяет получать структурированную документацию.

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

Принципы документирования кода

При работе с Doxygen на выходе можно получить:

• HTML
• LaTeX (PDF)
• MS Word
• Пользовательские XML-файлы

Как работает Doxygen:

• Выполняется парсинг текстовых файлов проекта и извлечение блоков документации.
• Специальные символы форматирования заменяются соответствующими стилями или командами.
• Интерпретируются специальные команды и HTML-теги (для LaTeX создаются аналоги).
• Генерируются связи и гиперссылки между сущностями.

Блоки документирования

Для каждой описываемой сущности допустимы два вида комментариев:

• Краткое описание (brief)
• Подробное описание (detailed)

Рекомендуется использовать оба, но не более одного каждого на сущность.

Виды сущностей и команд:

• \class — класс (C++)
• \struct — структура (C)
• \union — объединение
• \enum — перечисление
• \fn — функция
• \var — переменная / значение enum
• \def — директива #define
• \typedef — определение типа
• \file — файл проекта
• \namespace — пространство имён
• \package — пакет Java
• \interface — IDL-интерфейс

Конфигурирование Doxygen

Конфигурационный файл проекта — это Doxyfile (по умолчанию) или default.doxygen.

Формат:

TAGNAME = VALUE

Примеры:

• OPTIMIZE_OUTPUT_FOR_C = YES
• INPUT_ENCODING = CP1215

Сгенерировать Doxyfile можно так:

doxygen -g Doxyfile

Рекомендуется размещать Doxyfile в корне проекта.

Заголовочный файл и README

Чтобы использовать README.md или README.h как главную страницу:

USE_MDFILE_AS_MAINPAGE = README.md

GUI: программа Doxywizard

Doxywizard — графическая оболочка для Doxygen. Позволяет редактировать Doxyfile визуально.

Запуск:

doxywizard

Узнать версию:

doxywizard --version

Установить утилиты:

sudo apt install -y doxygen doxygen-doc doxygen-latex doxygen-gui graphviz

Graphviz позволяет визуализировать связи:

• Графы вызовов (Call Graph)
• Диаграммы взаимодействия (Collaboration Graph)
• Иерархии классов (Class Graph)

Результаты работы и форматы вывода

• HTML: интерактивная навигация по документации, ссылки кликабельны.
• MS Word: аналогично, со всеми гиперссылками.
• LaTeX → PDF: оформленный текстовый вариант.

Команды для генерации:

OUTPUT_DIRECTORY = docs
EXTRACT_ALL = YES
RECURSIVE = YES

doxygen Doxyfile

Открыть результат: docs/html/index.html

Изменение имени проекта:

PROJECT_NAME = "Your_project_name"

Ошибки компиляции документации

Ошибки отображаются в поле вывода Output produced by doxygen.

Например:

• tag without matching — может указывать на неправильную строку.

Дополнительно

• Команды можно использовать как через @, так и \.
• Синтаксис похож на Javadoc (/** ... */, ///, /*! ... */).
• Поддержка HTML-тегов, например <br>.
• Возможность добавлять собственные теги.
• Комментарии к строке: код; ///< комментарий

Полезные ссылки:

• Официальный сайт Doxygen
• Вывод в различных форматах
• Форматирование списков
• Список специальных команд
• Полная документация