Автодокументирование с помощью Doxygen

Doxygen — это кроссплатформенная система документирования исходников, которая поддерживает языки: C/C++, Obj-C, Python, Java, IDL, PHP, C#, Fortran, TCL и VHDL.

Doxygen обеспечивает автодокументирование путем обработки спецкомментариев, размещаемых в исходном коде.

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

Команд Doxygen больше 200. Мы рассмотрим только самые нужные из них. Полный список команд-директив приведён в официальной документации.

Де-факто Doxygen стал основным, определяющим стандартом документирования из аннотированных C/C++ исходников. Фактически система работает как компилятор, анализируя спецкомментарии и создавая из них документацию.

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

Имплементация Doxygen подразумевает внедрение специального синтаксиса, который используется для оформления блоков с комментариями.

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

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

В результате, для создания документации достаточно просто писать комментарии в коде, придерживаясь нескольких простых правил.

Для многострочного комментария используется конструкция:
/** ваш комментарий */

Для однострочного комментария используется конструкция:
/// ваш комментарий

Иногда нужно расположить комментарий после, либо на одной строке с описываемым элементом.

Пример:

int x_stdn2_est; /// Подробный комментарий
                 /// Подробный комментарий продолжение

Отметим, что Doxygen позволяет формировать документацию в нескольких форматах:
• HTML (генерация онлайн документация для WEB браузеров )
• XML
• RTF
• MAN
• LATEX

Также вывод может быть легко конвертирован в CHM, PostScript и PDF формат.

Doxygen портирован на все популярные операционные системы: Mac OS, Linux, Unix и Windows.

Вывод Doxygen может содержать в себе таблицы, списки, ссылки, диаграммы, графы, иерархические указатели и т.п.

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

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

Документирование функций и методов

Для описания методов и функций используются следующие основные теги:

@arg
Описание параметров, передаваемых функции.

@brief
Краткое описание сущности.

@detailed
Подробное описание сущности.

@example
Указывает, что блок комментариев содержит пример использования чего-либо.

@internal
Указывает, что фрагмент предназначен только для внутреннего использования

@param
Описание параметров, передаваемых функции.

@pre
Начальные условия

@post
Конечные условия

@return
Описание значения, возвращаемого функцией.

@retval
Для более подробного описания возвращаемых значений

@see
Ссылки на классы, функции, методы, переменные, файлы, URL и пр.

В результате документирования функции получаем примерно следующее:

/**
 * @brief:  removeFolder()
 *          Удалить содержимое директории
 *
 * @param:  [in] dir Директория, которую необходимо очистить.
 * @param:  [in] rmdir флаг (параметр удаления): 
 *                   false – удалить только внутренние папки и файлы
 *                   true  – удалить и корневую директорию
 * @retval: true  Успешное выполнение
 * @retval: false Ошибка выполнения
 */
bool removeFolder( const oDir * dir, bool rmdir );

Чтобы привести пример работы используется конструкция @code – @endcode:

/**
@code: Пример использования Foo:
       Foo f();
       f.Run();
@endcode
 */

Список команд документирования файлов:

@mainpage
Используется для указания основной (начальной) страницы проекта
Пример: @mainpage Главная страница

@page
Служит для указания дополнительного раздела документации
Пример: @page page1 — Страница 1

@ref
Используется для указания ссылок на другие страницы документации
Пример: @ref page1

@file
Краткое описание файла
Пример: @file file.h

@link
Ссылка на файл, код, описание, объект, документацию, emal и пр.
Пример: @link lomako@mcst.ru

@author
Служит для указания автора
Пример: @author Ivanov I.I.

@date
Дата написания файла
Пример: @date February, 2014

@defgroup
Задаёт группу в большом проекте для разделения на подпроекты.
Пример: @defgroup group — Админы

@version
Используется для указания версии

В результате для описания файла проекта используем следующий блок команд:

/**
 * @defgroup: group Модуль работы с внешними данными
 * @file:     zone.h
 * @brief:    Реализует операции взаимодействия с внешними источниками
 * @date:     February, 2014
 * @author    Ivanov I.I.
 */

Описание групп в Doxygen

@name
Описание группы чего-либо одним комментарием.

Пример:

/@ {
/// @name Функции инициализации / деинициализации
…
//@ }

Ремарки в Doxygen

Для добавления замечаний в код используются следующие команды/теги:
@attention
@bug
@todo
@note
@warning

Имя команды определяет тип замечания/ремарки, и каждая команда вставляет соответствующую заметку. Для них Doxygen формирует отдельные списки, по которым можно быстро найти нужное место в коде.

Примеры:

/// @warning Не трогать значение этой переменной
/// @todo    Переписать функцию под новую структуру данных
/// @bug     Ошибочно работает при x < 0
/// @note    Подробнее изложено в рабочем журнале

Другие интересные команды

@class :
Описание класса

@struct :
Документирует структуру

@union :
Документирует объединение

@enum :
Документирует перечисление

@fn :
Документирует функцию

@var :
Документирует переменную

@def :
Документирует макрос

@namespace:
Документирует пространство имен

@typedef :
Документирование объявления типа

@interface:
Документирование интерфейса

@package :
Документирование пакета

Настройка Doxygen

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

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

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

Ниже показаны наиболее интересные теги конфигурационного файла:

PROJECT_NAME      Имя проекта
QUIET             Режим тишины. Допустимые значения YES и NO (default: NO)
                  YES, чтобы важные предупреждения не потерялись среди обилия информации
WARN_NO_PARAMDOC  YES - для вывода предупреждений о недокументированных аргументах функции
INPUT             Путь к анализируемому коду. 
                  Рекомендуется в корне проекта создать директорию docs содержащую Doxyfile 
                  с настройками, в таком случае значение этого параметра будет ../
FILE_PATTERNS     Шаблон для имени анализируемых файлов 
                  Поскольку документироваться должны только открытые интерфейсы, 
                  то очевидно, что следует анализировать только заголовочные файлы: *.h
RECURSIVE         YES - рекурсивно анализировать файлы в поддиректориях
EXCLUDE_PATTERNS  Исключение из анализа директорий соответствующих маске.
                  Пример:
                  EXCLUDE_PATTERNS = */.svn/* */build/* */tests/* */sources/*
HAVE_DOT          YES - если установлен Graphviz и требуется визуализация связей.

Тегов настройки у Doxygen более чем достаточно. Чтобы облегчить работу можно выполнить команду: doxygen -g и конфигурационный файл с именем Doxyfile будет создан автоматически.

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

Запуск Doxygen

Запуск системы автодокументирования очень прост – для этого надо запустить Doxygen указав ему путь к конфигурационному файлу:

doxygen path/to/config-file

В зависимости от настроек будут созданы html, rtf, latex, xml, man каталоги в директории выгрузки. Как подсказывают названия, эти каталоги содержат сгенерированную документацию в HTML, RTF, LaTeX, XML и Unix-Man Page форматах.

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

Формат конкретного каталога с документацией в директории выгрузки может быть выбран с использованием тегов: HTML_OUTPUT, RTF_OUTPUT, LATEX_OUTPUT, XML_OUTPUT и MAN_OUTPUT

Если OUTPUT_DIRECTORY не пуст, а такой директории выгрузки не существует, Doxygen создаст её для Вас.

Вывод в HTML

Для того, чтобы просмотреть сгенерированную HTML документацию нужно указать в адресной строке браузера путь к файлу index.html в каталоге html. Для получения лучших результатов, браузер должен поддерживать CSS.

Некоторые из возможностей, такие как GENERATE_TREEVIEW, требуют браузер, который поддерживает DHTML и Javascript.

Если Вы планируете использовать средства поиска (см. SEARCHENGINE), то просматривайте HTML вывод через WEB-сервер поддерживающий PHP (пример, Apache с предустановленным PHP модулем).

Вывод в RTF

Doxygen объединяет вывод в RTF в один файл с именем refman.rtf. Этот файл оптимизирован для импорта в Microsoft Word.

Для кодирования точной информации используйте поля. Чтобы показать реальное значение, Вам нужно выбрать все (Edit - select all) и затем включить поля (щелкнуть правой кнопкой мыши и выбрать опцию из выпадающего меню).

Вывод в LaTeX

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

Содержание и цели в Makefile зависят от значения тега USE_PDFLATEX.

Если тег USE_PDFLATEX установлен в NO), то выполнив make без аргументов в каталоге latex будет сгенерирован dvi файл, вызывающий refman.dvi. Этот файл может быть просмотрен с помощью xdvi или сконвертирован в PostScript файл refman.ps путем запуска make ps (это требует наличия dvips).

Чтобы разместить 2 страницы на одной физической странице используйте make ps_2on1. Результирующий PostScript файл может быть отправлен на PostScript принтер. Если у Вас нет PostScript принтера, Вы можете попытаться использовать ghostscript, чтобы сконвертировать PostScript в формат который понимает Ваш принтер.

Конвертирование в PDF формат возможно если установлен интерпритатор ghostscript.

Для генерации документации в формате PDF выполните make pdf (или make pdf_2on1). Будет построен файл refman.pdf.

Если тег USE_PDFLATEX установлен в YES), то для конвертирования вывода в формат PDF достаточно запустить make без аргументов или make pdf_2on1.

Чтобы получить более наглядный PDF файл, можно установить тег PDF_HYPERLINKS .

Вывод в XML

XML вывод состоит из кучи структурированной информации, собранной Doxygen. Каждой структуре class/namespace/file/... соответствует свой собственный XML файл и индексный файл с именем index.xml.

Также генерируется файл с именем combine.xslt (XSLT script), который может быть использован для объединения всех XML файлов в один файл.

Doxygen также генерирует два файла-схемы XML: index.xsd (для индексного файла) и compound.xsd (для файлов со структурой).

Этот файл-схема описывает возможные элементы, их атрибуты и как они структурированы, то есть он описывает грамматику XML файлов и может быть использован для проверки или управления XSLT скриптами.

В каталоге addon/doxmlparser Вы можете найти библиотеку парсера для чтения XML выгрузки (см. addon/doxmlparser/include/doxmlintf.h для получения интерфейса к библиотеке).

Вывод в Man

Сгенерированные страницы man могут быть просмотрены с помощью программы man. Вым нужно убедиться, что директория с man файлами прописана в пути (смотрите переменную окружения MANPATH). Заметим, что существуют некоторые ограничения возможностей формата man page, в следствие чего некоторые данные (такие как диаграммы классов, перекрестные ссылки и формулы) будут утеряны.