Настройка генератора документации

Специальная разметка

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

Команды должны быть написаны внутри комментария, воспринимаемого doxygen, причем команда начинается с префикса \ или @.

/**

@brief Функция делает что-то

@param pArr – массив элементов

@param param1 –количество элементов в массиве

*/

void func(const long * pArr, int count);

В примере иллюстрируются команды @brief и @param, позволяющие указать, что текст является кратким описанием самой функции и перечислить параметры. Это позволит doxygen стилистически правильно оформить описание функции и её параметров.

Полный список команд приводится в документации doxygen-manual в разделе Special Commands. Перечислим наиболее часто используемые команды.

Команда	Назначение
@brief	Кратное описание сущности, к которой относится данная команда (структура данных, функция, файл, страница текста). Краткие описания в итоговом отчете отображаются в таблицах с именами сущностей, к котором они относятся (по группам).
@details	Подробное описание сущности, к которой относится данная команда
@file	Имя файла, в котором находится описание. Позволяет формально отделить секцию, относящуюся к описанию файла, например от секции описания класса.
@addtogroup	При создании больших программных библиотек исходный код разбивается на модули. В то же время необходима единая документация на все исходные тексты. В этом случае целесообразно разбить описываемые разделы на группы, например по принципу отнесения исходных текстов к тому или иному модулю. Соответственно, команде addtogroup указывают имя группы, к которой необходимо отнести текущий файл.
@param	Описание параметра функции или метода. Для каждого параметра необходимо указывать свою команду param
@return	Описание возвращаемого значения функции.
@class	Указывает, что имя, после команды является классом.
@fn	Указывает, что имя, после команды является функцией.
@struct	Указывает, что имя, после команды является структурой.
@mainpage	Команда для добавления текста на заглавную страницу отчета.

Doxygen является консольным приложением, выполняющим формирование отчета в соответствии с заданными в параметрами, которые могут находиться например в файле doxyfile. Этот файл является текстовым, где перечислены параметры doxygen и их значения. Параметрами задаются директории с исходными текстами программ, опции обработки текстов, опции формирования результата. Для облегчения создания и управления этим файлом существуют графические оболочки, например doxywizard или doxygate.

Рассмотрим создание документации при помощи программы doxywizard. После запуска doxywizard (в меню Пуск/Программы/doxygen) будет отображено окно, подобно изображенному на рисунке 2.

Рисунок 1 – Окно doxywizard. Ввод основных параметров.

Необходимо указать рабочую директорию (working directory), т.е. директорию, в которой будет размещаться временные файлы при создании документации, указать имя проекта (Project name), директорию с исходными кодами (Source code directory), а также директорию, в которую будет помещена документация (Destination directory). Если в проекте исходные тексты размещены в нескольких поддиректориях необходимо отметить “Scan recursively”.

После настройки основных параметров следует переключиться к закладке Mode (см. рисунок 3).

Рисунок 2 – Окно doxywizard. Ввод параметров обработки текстов.

Выбор режима обработки исходных текстов позволяет указать что конкретно требуется анализировать и для какого языка программирования. Например Extraction mode All Entries означает, что в документацию будут вынесены абсолютно все сущности, найденные в исходных текстах, а не только те, которые имеют специальную разметку. Флаг Include cross-referenced source code in the output означает, что в документацию будут помещены ссылки, позволяющие позиционироваться с их помощью на нужную строку нужного файла исходный кода.

Рисунок 3 – Окно doxywizard. Ввод режима формирования результата.

Параметры вывода (рисунок 3) подразумевают выбор формата, в котором, будет сформирована документация. Наиболее часто используется формат HTML. Режим plain text предполагает создание страниц описания с гиперссылками. Формат With frames and a navigation tree позволит создать html-документацию, где помимо страниц описания будет присутствовать отдельное окно с деревом имен сущностей проекта. Флаг With search function целесообразно использовать лишь в тех случаях, когда документацию планируется размещать на WEB-сервере.

Рисунок 4 – Окно doxywizard. Выбор режима формирования диаграмм.

В состав документации могут быть помещены диаграммы (рисунок 4) среди которых диаграммы классов, диаграмма взаимодействии, диаграмма иерархии классов, графы зависимостей файлов исходных текстов, графы вызова функций. Для их построения требуется наличие специальной библиотеки GraphViz и средства dot.

Рисунок 5 – Дополнительные настройки doxywizard. Режим анализа текстов.

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

Язык документации (т.е. надписи обрамления) выбирается в группе Project – OUTPUT_LANGUAGE.

Рисунок 6 – Дополнительные настройки doxywizard. Формат исходных данных.

Среди параметров группы Input (рисунок 6) должен быть указан INPUT_ENCODING в том случае, если в исходных текстах присутствуют комментарии, написанные буквами отличными от основного латинского алфавита. В частности cp1251 обозначает кодировку Windows.

Рисунок 7 – Дополнительные настройки doxywizard. Выбор типов диаграмм.

Если необходимо построить диаграммы, то в группе Dot (рисунок 7) следует указать, что используется программа dot (генератор изображений по текстовому описанию) – HAVE_DOT, а также указать директорию, в которой расположена эта программа – DOT_PATH. Программа dot входит в комплект GraphViz и в случае, когда директория DOT_PATH указана в переменной окружения операционной системы PATH, указывать путь здесь уже не требуется.

Рисунок 8 – Запуск doxygen.

После того, как заполнены значения всех необходимых параметров, можно сохранить файл параметров на диск(меню File/Save) и запустить генератор документации, нажав кнопу Run doxygen (рисунок 8).

Дата добавления: 2014-11-25