С.В. Герасимов, И.В. Машечкин, М.И. Петровский и др. - Инструментальные средства разработки ПО в ОС UNIX, страница 10

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

Параметрыпостроения документации хранятся в конфигурационном файле,имеющем текстовый формат.60Документирование исходного кодаБлоки комментариевДля документирования исходного кода используются блокикомментариев в стиле Си/Си++ с использованием дополнительнойразметки. Для каждой сущности программы могут быть заданыописания двух типов: подробное и краткое (для функций такжесуществует третий тип описания – «в теле»). Краткое описание –однострочное, подробное – более детализированное многострочное,описание «в теле», как правило, используется для описанияреализации функции.Существует несколько способов отметить блок комментариякак подробное описание:1.

Многострочный комментарий, начинающийся с двух или более«*», т.н. JavaDoc стиль описания:/*** Подробное* описание*/Промежуточные ‘*’ не обязательны:/**Подробноеописание*/2. Многострочный комментарий, начинающийся с «/!*». Описаниев стиле QT./*!* Подробное* описание*/3. Три или более однострочных комментария Си/Си++, где каждаястрока начинается с «///» или «//!»:////// Подробное/// описание///и:61//!//! Текст//!4. Более выделенные в исходном коде блоки комментариев:/********** Подробное* описание**********/и://////////////////////// Подробное/// описание/////////////////////Способы создания краткого описания:1.

Использование команды brief:/*** @brief Краткое* описание** Полное описание*/В данном случае краткое и полное описания разделяются пустойстрокой.2. Использованиережимаконфигурационном файле.JAVADOC_AUTOBRIEF=YESвВ данном режиме краткое описание не требует отдельной команды изавершается точкой либо новой строкой:/*** Краткое описание. Полное описание*/3. Разделение на несколько блоков:/// Краткое описание/*** Полное* описание*/62или:/// Краткое описание/// Полное/// описаниеОбязательна пустая строка между кратким и полным описанием.Документирование функцийДля документирования параметров функции используется командаparam, возвращаемых значений - return:/*** Двоичный поиск в упорядоченном массиве.** В случае нескольких вхождение одного и того же элемента,возвращается индекс произвольного.** @param[in] array массив чисел* @param[in] len длина массива* @param[in] elem искомый элемент* @param[out] posBefore при отсутствии искомого элемента в массиве* через posBefore возвращается индекс ближайшего** @return Индекс (начиная с 0) найденного элемента либо -1.*/int _bsearch (int * array, int len, int elem, int * posBefore);Задавать тип параметра in (входной) / out (выходной) необязательно.Фрагмент сгенерированного Doxygen описания данной функции (сдиаграммой вызова данной функции):63Запуск DoxygenВ результате выполнения командыdoxygen –g <имя конфигурационного файла>Doxygen создаст новыйконфигурационныйконфигурационного файла по умолчанию Doxygen.файл.ИмяДля использования Doxygen при документировании исходныхфайловнаСиможетпригодитьсяопция«OPTIMIZE_OUTPUT_FOR_C = YES».

Также может быть полезнаопция «JAVADOC_AUTOBRIEF = YES» для интерпретации первойстроки комментария как краткого комментария без указаниякоманды @brief. Для выбора кодировки исходных текстов илокализации файла документации существуют параметры«INPUT_ENCODING» и «OUTPUT_LANGUAGE».После редактирования файла можно использовать командуdoxygen <имя конфигурационного файла>для генерации документации.64В Makefile может быть создана соответствующая цель,отвечающая за генерацию документации:doc:doxygenДля визуального редактирования опций конфигурационногофайла и запуска генерации документации в состав Doxygen входитграфическая утилита doxywizard:Полныйпереченькомандразметкииопцийконфигурационного файла можно найти в документации Doxygen.65.