Doxygen — это кросплатформенная система для получения документации на основе исходных текстов. Система поддерживает C++, C, Java, Objective-C, Python, IDL(CORBA и MIDL), Fortran, VHDL, PHP, C# и, частично, D.
Doxygen выбирает документацию из комментариев сделанных в коде, но может быть полезен и при работе с недокументированными исходными текстами, оформив структуру кода: он строит прекрасные диаграммы классов и графы зависимостей, а также оформляет код гиперссылками. Вывод можно получить в HTML или LaTeX и может легко быть сконвертирован в CHM или PDF. Кроме этого, doxygen имеет встроенную поддержку генерации документации в формате man, RTF и XML.
Чтобы получить документацию требуется совсем немного усилий.
Во-первых, код должен содержать комментарии, оформленные надлежащим образом, во-вторых, нужен сам генератор документации Doxygen.
Документация кода
Специальные комментарии
Специальный комментарий помечается символом '!' сразу после начала комментария. Такой комментарий должен стоять перед конструкцией которую он описывает. Пустая строка создает новый абзац.
Если требуется поставить специальный комментарий после конструкции, используется последовательность '!<' сразу после начала комментария. Кстати, кроме символа '!', для обозначения специальных комментариев, можно использовать последовательность символов '/**' для многострочного комментария, а для однострочного — последовательность '///'.
Пример:
#define TRUE 0 /*!< Передо мной объект который я описываю */
struct abc
{
int a; //!< Поле a
int b; //!< Поле b
int c; //!< Поле z
};
//! Функция main() − точка входа в программу.
/*! Текст специального комментария.
* Этот текст попадет в документацию Doxygen.
* Кстати, символы оформления ’*’ в начале строк
* в документации отображаться не будут.
*
* Новый абзац.
*/
/* !А этот текст не попадет в документацию,
* это обычный комментарий
*/
int main (void)
{
return 0;
}
Первое предложение специального комментария (до первой точки) Doxygen принимает за краткое описание, оно используется в заголовках документации, где обычно содержится список разных
конструкций и вполне достаточно краткого описания. Если присутствует однострочный комментарий, Doxygen возьмет его в качестве краткого описания.
Документация функций
Для оформления документации параметров функции и возвращаемого значения используются команды param и return.
Пример:
/*! Копирует содержимое src в буфер dst.
* \param [in] dst − адрес буфера назначения
* \param [in] src − адрес источника
* \param [in] n − количество байт для копирования
* \return адрес назначения dst
*/
void *memcpy(void *dst , const void *src, size_t n);
Списки
Чтобы представить список в документации, используется символ '-', отделенный пробелом от строки.
Вложенность списков задается отступами: строки с одинаковым количеством отступов относятся к одному уровню вложенности.
При помощи комбинации '-#' можно получить нумерованные списки.
Пример:
/*! Список:
* − строка1;
* −# строка1.1 нумерованного списка;
* −# строка1.2 нумерованного списка;
* − строка2;
* − строка3.
*/
Группы
При помощи групп, несколько выражений можно вынести в отдельную страницу документации и вставлять перекрестные ссылки на эту страницу.
Группа создается при помощи команды \defgroup <имя_группы> <Заголовок страницы> и выделяется парами символов '@{' и '@}'.
Пример:
/* \defgroup groupA Буквы алфавита
@{ */
#define A 1
#define B 2
#define C 3
char abc_letter;
/* }@ */
Ссылки
В документации можно создавать гиперссылки на элементы кода и группы. Ссылка на элемент кода создается путем добавления символа '#' перед ним, а для ссылки на группу используется команда \ref <имя_группы>.
Ссылки удобно помещать в секцию 'Смотри также', которая объявляется при помощи команды \sa.
Пример:
/*! Функция увеличивает значение
* переменной #abc_letter на 1.
* \sa \ref groupA
*/Утилита Doxygen
Установка
Для создания документации понадобится дистрибутив Doxygen отсюда и пакет утилит Graphviz для построения графов отсюда. Для получения CHM файлов, потребуется HTML Help Workshop отсюда.
Настройка
В дистрибутив Doxygen входит утилита Doxywizard, c помощью которой производится настройка и работа с Doxygen.
На закладке Wizard производятся основные настройки, после указания пути к проекту и выходных файлов можно сразу переходить к закладке Run, нажать кнопку Run doxygen и получить результат.
Для более тонкой настройки используется закладка Expert, где располагается множество разнообразных опций утилиты. Например, здесь можно указать входную кодировку (INPUT_ENCODING), указать путь к html help compiler (HHC_LOCATION), разрешить включение исходного кода в документацию (INLINE_SOURCES) и многое другое.
Сделав настройку при помощи Doxywizard, настройки можно сохранить в файл и использовать его при запуске утилиты doxygen из командной строки. Таким образом, например, можно обновлять документацию вместе с компиляцией кода, добавив соответствующую команду в make-файл или в post-build event.
Данная статья не является исчерпывающей документацией по использованию doxygen, более полную информацию можно получить на сайте doxygen или из справки, поставляемой вместе с утилитой.
Ссылки:
- Сайт doxygen
- Частично переведенная на русский документация здесь
- Примеры документации полученной при помощи doxygen здесь