Это руководство разделено на три части, каждая из которых разделена на несколько секций.
Первая часть составляет руководство пользователя:
- В секции Инсталяция обсуждается как скачать, скомпилировать и установить doxygen на Вашу платформу.
- Секция Быстрый старт расскажет как быстро сгенерировать Вашу первую документацию.
- Секция Документирование кода демонстрирует различные способы документирования кода.
- Секция Списки покажет различные способы создания списков.
- Секция Группировка показывает, как объединять информацию.
- Секция Включение формул показывает как вставить формулы в документацию.
- Секция Графы и диаграммы описывает диаграммы и графы, которые может генерировать doxygen.
- Секция Предварительная подготовка объясняет, как doxygen ведет себя с макроопределениями.
- Секция Генерация автоматических ссылок показывает, как поместить ссылки на файлы, классы и члены в документацию.
- Секция Выходные форматы показывает, как генерировать выходные форматы, которые поддерживает doxygen.
- Секция Настройка вывода объясняет, как Вы можете настроить вывод генерируемый doxygen.
- Секция Настраиваемые команды показывает, как определять и использовать настраиваемые команды в Ваших комментариях.
- Секция Связь с внешней документацией объясняет, как doxygen может создавать ссылки на внешнюю документацию.
- Секция Часто задаваемые вопросы дает ответы на часто задаваемые вопросы.
- Секция Поиск неисправностей рассказывает Вам, что нужно сделать для решения возникших проблем.
Вторая часть составляет справочник:
- Секция Особенности представляют краткий обзор того, что может сделать doxygen.
- Секция Истоия Doxygen показывает то, что изменилось во время разработки doxygen и что все еще должно быть сделано.
- Секция Использование Doxygen показывает, как использовать Doxygen.
- Секция Использование Doxytag показывает, как использовать Doxytag.
- Секция Использование Doxywizard показывает, как использовать Doxywizard.
- Секция Использование Installdox показывает, как использовать Installdox скрипт, который генерирует doxygen, если Вы используете файл тегов.
- Секция Настройка показывает, как настроить doxygen, чтобы получить нужную документацию.
- Секция Специальные команды показывают краткий обзор специальных команд, которые могут использоваться в документации.
- Секция Команды HTML показывают краткий обзор команд HTML, которые могут использоваться в документации.
- Секция Команды XML делает краткий обзор команд XML в стиле C#, которые могут использоваться в документации.
Третья часть предоставляет информацию для разработчиков:
- Секция Внутреннее устройство Doxygen дает подробное оприсание внутреннего устройства Doxygen.
- Секция Выходной формат документации Perl Module показывает, как использовать вывод PerlMod.
- Секция Интернационализация объясняет, как добавить поддержку новых языков вывода.
Время на прочтение
18 мин
Количество просмотров 329K
Данная статья входит в получившийся цикл статей о системе документирования Doxygen:
- Документируем код эффективно при помощи Doxygen
- Оформление документации в Doxygen
- Построение диаграмм и графов в Doxygen
Это первая и основная статья из упомянутого цикла и она представляет собой введение в систему документирования исходных текстов Doxygen, которая на сегодняшний день, по имеющему основания заявлению разработчиков, стала фактически стандартом для документирования программного обеспечения, написанного на языке C++, а также получила пусть и менее широкое распространение и среди ряда других языков.
В этой статье мы сначала познакомимся с самой системой и её возможностями, затем разберёмся с её установкой и базовыми принципами работы, и, наконец, завершим знакомство рассмотрением различных примеров документации, примеров того, как следует документировать те или иные части кода. Словом, познакомимся со всем тем, что позволит вам освоиться и начать работать с этой замечательной системой.
Введение
Вероятнее всего, каждый из нас сталкивался с результатами работы различных генераторов документации. Общий принцип их работы следующий: на вход такого генератора поступает специальным образом комментированный исходный код, а иногда и другие компоненты программы, а на выходе создаётся готовая документация для распространения и использования.
Рассматриваемая система Doxygen как раз и выполняет эту задачу: она позволяет генерировать на основе исходного кода, содержащего комментарии специального вида, красивую и удобную документацию, содержащую в себе ссылки, диаграммы классов, вызовов и т.п. в различных форматах: HTML, LaTeX, CHM, RTF, PostScript, PDF, man-страницы.
Для того, чтобы составить общее впечатление о системе, ниже представлены примеры различных документаций для API, созданных при помощи Doxygen (следует обратить внимание, что в последние примеры внесены заметные изменения в сравнении со стандартной документацией, которую генерирует данная система):
- Документация к API игрового движка CrystalSpace
- Документация к Visualization Toolkit
- Документация к исходникам Abiword
- Документация к API KDE
- Документация к API Drupal
Внимательный читатель наверняка обратил внимание на то, что в большинстве примеров Doxygen используется для документации программного обеспечения, написанного на языке C++, однако на самом деле данная система поддерживает гораздо большое число других языков: C, Objective-C, C#, PHP, Java, Python, IDL, Fortran, VHDL, Tcl, и частично D.
Впрочем, следуя сложившейся традиции, в примерах я буду использовать C++, однако это не должно смущать вас, если вы предпочитаете другой поддерживаемый язык, поскольку особой разницы на практике вы даже не заметите, и большинство сказанного далее будет справедливо и для вашего языка.
К слову, список проектов, использующих Doxygen имеется на официальном сайте, причём большинство из этих проектов свободные. Поэтому желающие могут скачать исходник того или иного проекта и посмотреть как там разработчики осуществляли документацию.
Установка и настройка
Скачать последнюю версию Doxygen можно на официальном сайте, дистрибутивы которой доступны для большинства популярных операционных систем, кроме того, вы можете воспользоваться вашим пакетным менеджером. Помимо этого для комфортной и полнофункциональной работы рекомендуется установить Graphviz.
Далее работа с Doxygen весьма тривиальна: достаточно запустить программу, указав ей путь к файлу с настройками.
doxygen <config_file>
Но в этом файле и вся тонкость. Дело в том, что каждому проекту соответствует свой файл настроек, в котором может быть прописан путь до исходников проекта, путь, по которому должна быть создана документация, а также большое число других разнообразных опций, которые подробно описаны в документации, и которые позволяют максимально настроить документацию проекта под свои нужды.
В принципе, для редактирования данного файла и, вообще, работой с Doxygen, можно воспользоваться программой Doxywizard, которая чаще всего идёт вместе с Doxygen и которая позволяет чуть удобнее работать с файлом настроек (слева – Doxywizard; справа – файл открытый в текстовом редакторе):
Итак, приступим к созданию файла с настройками. Вообще, если вы используете Doxywizard, то он будет создан автоматически, в противном случае для создания этого файла необходимо запустить программу Doxygen с ключом -g (от generate):
doxygen -g <config_name>
Рассмотрим основные опции, которые могут вам пригодится, чтобы создать первую вашу документацию:
| Тэг | Назначение | По умолчанию |
| DOXYFILE_ENCODING | Кодировка, которая используется для всех символов в данном файле настроек | UTF-8 |
| OUTPUT_LANGUAGE | Устанавливает язык, на котором будет сгенерирована документация | English |
| PROJECT_NAME | Название проекта, которое может представлять собой единое слово или последовательность слов (если вы редактируете вне Doxywizard, последовательность слов необходимо поместить в двойные кавычки) | My Project |
| PROJECT_NUMBER | Данный тэг может быть использован для указания номера проекта или его версии | — |
| PROJECT_BRIEF | Краткое однострочное описание проекта, которое размещается сверху каждой страницы и даёт общее представление о назначении проекта | — |
| OUTPUT_DIRECTORY | Абсолютный или относительный путь, по которому будет сгенерирована документация | Текущая директория |
| INPUT | Список файлов и/или директорий, разделенных пробелом, которые содержат в себе исходные коды проекта | Текущая директория |
| RECURSIVE | Используется в том случае, если необходимо сканировать исходные коды в подпапках указанных директорий | NO |
После того, как мы внесли необходимые изменения в файл с настройками (например, изменили язык, названия проекта и т.п.) необходимо сгенерировать документацию.
Для её генерации можно воспользоваться Doxywizard (для этого необходимо указать рабочую директорию, из которой будут браться исходные коды, перейти на вкладку «Run» и нажать «Run doxygen») или запустив программу Doxygen, указав ей в качестве параметра путь к файлу с настройками:
doxygen <config_file>
Основы документирования на Doxygen
Теперь, когда мы разобрались с тем, как настраивать Doxygen и работать с ним, впору разобраться с тем, как необходимо документировать код, основными принципами и подходами.
Документация кода в Doxygen осуществляется при помощи документирующего блока. При этом существует два подхода к его размещению:
- Он может быть размещён перед или после объявления или определения класса, члена класса, функции, пространства имён и т.д.;
- Либо его можно располагать в произвольном месте (и даже другом файле), но для этого потребуется явно указать в нём, к какому элементу кода он относится. Мы не будет рассматривать этот подход, поскольку даже разработчики рекомендуют его избегать, но если интересно, то подробнее о нём можно прочитать в документации.
Структурно, любой документирующий блок является комментарием, просто оформленным специальным образом, поэтому естественно, что его вид зависит от используемого языка (подробнее об этом можно прочитать в соответствующем разделе документации). Поэтому далее мы остановимся на рассмотрении синтаксиса для C-подобных языков (C/C++/C#/Objective-C/PHP/Java).
Сразу отметим, что, вообще, всего существует два основных типа документирующих блоков: многострочный блок и однострочный блок.
Разница между ними чуть более сильная, чем между однострочным и многострочным комментарием. Дело в том, что текст, написанный в однострочном блоке относится к краткому описанию документируемого элемента (сродни заголовку), а текст, написанный в многострочном блоке относится к подробному описанию. Про эту разницу не следует забывать.
Многострочный блок
Мы сказали, что любой блок – это комментарий, оформленный специальным образом. Поэтому необходимо определить каким таким «специальным образом». Вообще, существует целый ряд способов для описания многострочного блока, и выбор конкретного способа зависит от ваших предпочтений:
- JavaDoc стиль (напоминает обычный C комментарий, но начинающийся с двух звездочек):
/** * ... первая строчка ... * ... вторая строчка ... */При этом звездочки не обязательно ставить на каждой строке. Такая запись будет эквивалентной:
/** ... первая строчка ... ... вторая строчка ... */ - Qt стиль, в котором в начале вместо второй звёздочки ставится восклицательный знак:
/*! * ... первая строчка ... * ... вторая строчка ... */Сказанное о необязательности промежуточных звездочек также остаётся справедливым. Помимо названных двух стилей есть ещё ряд, но на них пока мы не будем останавливаться.
При этом ещё раз обратите внимание на то, что текст написанный в таком комментарии относится к подробному описанию.
Для указания краткого описания может быть использована команда \brief. Указанный после команды текст, вплоть до конца параграфа будет относится к краткому описания, и для отделения подробного описания и краткого описания используется пустая строка.
/*!
\brief Краткое описание и
его продолжение.
Подробное описание
*/
Однострочный блок
Для описания однострочного блока опять же существует целый ряд способов оформления, рассмотрим два из них:
- Можно использовать специальный комментарий в C++ стиле:
/// Краткое описание - Можно использовать аналогичный предыдущему комментарий, только вместо дополнительного слеша в нем ставится восклицательный знак:
//! Краткое описание
При этом хотелось бы обратить внимание на два момента:
- Для указания подробного описания в однострочном документирующем блоке может быть использована команда \details:
/// \details Подробное описание - Документирующие блоки, следующие друг за другом, объединяются в один (причем вне зависимости от используемого стиля и того, являются они многострочными или однострочными).
Например следующие два способа документирования дадут один и тот же результат:
/// \brief Краткое описание /// \details Подробное описание///Краткое описание /*! Подробное описание */
Да, Doxygen крайне гибок в плане способов документирования, однако не стоит этим злоупотреблять, и в рамках одного проекта всегда придерживайтесь заранее оговоренного единообразного стиля
Размещение документирующего блока после элемента
Во всех предыдущих примерах подразумевалось, что документирующий блок предварял документируемый элемент, но иногда бывают ситуации, когда удобнее разместить его после документируемого элемента. Для этого необходимо в блок добавить маркер «<«, как в примере ниже:
int variable; ///< Краткое описание
Пример документации
Теперь рассмотрим то, как это будет выглядеть на практике. Ниже представлен документированный код некоторого класса в соответствии с теми правилами, которые мы рассматривали ранее.
/*!
\brief Родительский класс, не несущий никакой смысловой нагрузки
Данный класс имеет только одну простую цель: проиллюстрировать то,
как Doxygen документирует наследование
*/
class Parent {
public:
Parent();
~Parent();
};
В итоге Doxygen сформирует на основе данных комментариев следующую красиво оформленную страничку (здесь приведена вырезка из неё):
Теперь, когда мы научились основам, пришла пора познакомиться с тем, как можно детализировать документацию. Инструментом для этого являются команды.
Команды
С несколькими из команд в Doxygen мы успели познакомиться (речь идёт о \brief и \details), однако на самом деле их значительно больше. Полный их список приведён в официальной документации.
Вообще, любая команда в Doxygen представляет собой слово на английском языке предваренное символом «\» или «@» (обе записи тождественны) и таких команд очень много, порядка двухсот. Приведём для примера несколько таких команд:
| Команда | Значение |
| \authors | Указывает автора или авторов |
| \version | Используется для указания версии |
| \date | Предназначена для указания даты разработки |
| \bug | Перечисление известных ошибок |
| \warning | Предупреждение для использования |
| \copyright | Используемая лицензия |
| \example | Команда, добавляемая в комментарий для указания ссылки на исходник с примером (добавляется после команды) |
| \todo | Команда, используется для описания тех изменений, которые необходимо будет сделать (TODO). |
Пример использования некоторых команд и результат приведены ниже:
/*!
\brief Дочерний класс
\author Norserium
\version 1.0
\date Март 2015 года
\warning Данный класс создан только в учебных целях
Обычный дочерний класс, который отнаследован от ранее созданного класса Parent
*/
class Son : public Parent {
public:
Son();
~Son();
};
Далее будут использоваться следующие обозначения при описании аргументов команды, когда будет приводиться её общий формат:
| Обозначение | Значение |
| <…> | Угловые скобки показывают, что аргумент представляет собой одно слово |
| (…) | Круглые скобки показывают, что аргументом является весь текст вплоть до конца строки, на которой размещена команда |
| {…} | Фигурные скобки показывают, что аргументом является весь текст вплоть до до следующего параграфа. Параграфы разделяются пустой строкой или командой-разделителем |
Кроме того, обратите внимание на то, что вы можете создавать и собственные команды. Подробно об этом можно прочитать в соответствующем разделе документации.
Документирование основных элементов исходного кода
Теперь мы можем рассмотреть специфичные особенности документирования различных элементов исходного кода, начиная от файлов в целом и заканчивая классами, структурами, функциями и методами.
Документирование файла
Хорошей практикой является добавление в начало файла документирующего блока, описывающегося его назначение. Для того, чтобы указать, что данный блок относится к файлу необходимо воспользоваться командой \file (причём в качестве параметра можно указать путь к файлу, к которому относится данный блок, но по умолчанию выбирается тот файл, в который блок добавляется, что, как правило, соответствует нашим нуждам).
/*!
\file
\brief Заголовочный файл с описанием классов
Данный файл содержит в себе определения основных
классов, используемых в демонстрационной программе
*/
#ifndef CLASSES_H
#define CLASSES_H
...
#endif // CLASSES_H
Документирование функций и методов
При документировании функций и методов чаще всего необходимо указать входные параметры, возвращаемое функцией значение, а также возможные исключения. Рассмотрим последовательно соответствующие команды.
Параметры
Для указания параметров необходимо использовать команду \param для каждого из параметров функции, при этом синтаксис команды имеет следующий вид:
\param [<направление>] <имя_параметра> {описание_параметра}
Рассмотрим значение компонентов команды:
- Имя параметра – это имя, под которым данный параметр известен в документируемом коде;
- Описание параметра представляет собой простое текстовое описание используемого параметра..
- Направление – это опциональный атрибут, который показывает назначение параметра и может иметь три значения «[in]», «[out]», «[in,out]»;
Сразу же перейдём к примеру:
/*!
Копирует содержимое из исходной области памяти в целевую область память
\param[out] dest Целевая область памяти
\param[in] src Исходная область памяти
\param[in] n Количество байтов, которые необходимо скопировать
*/
void memcpy(void *dest, const void *src, size_t n);
В результате мы получим такую вот аккуратную документацию функции:
Возвращаемое значение
Для описание возвращаемого значения используется команда \return (или её аналог \returns). Её синтаксис имеет следующий вид:
\return {описание_возвращаемого_значения}
Рассмотрим пример с описанием возвращаемого значения (при этом обратите внимание на то, что параметры описываются при помощи одной команды и в результате они в описании размещаются вместе):
/*!
Находит сумму двух чисел
\param a,b Складываемые числа
\return Сумму двух чисел, переданных в качестве аргументов
*/
double sum(const double a, const double b);
Получаем следующий результат:
Исключения
Для указания исключения используется команда \throw (или её синонимы: \throws, \exception), которая имеет следующий формат:
\throw <объект-исключение> {описание}
Простейший пример приведён ниже:
\throw std::bad_alloc В случае возникновения ошибки при выделении памяти
Документирование классов
Классы также могут быть задокументированы просто предварением их документирующим блоком. При этом огромное количество информации Doxygen получает автоматически, учитывая синтаксис языка, поэтому задача документирования классов значительно упрощается. Так при документировании Doxygen автоматические определяет методы и члены класса, уровни доступа к функциям, дружественные функции и т.п.
Если ваш язык не поддерживает явным образом определенные концепции, такие как например уровни доступа или создание методов, но их наличие подразумевается и его хотелось бы как-то выделить в документации, то существует ряд команд (например, \public, \private, \protected, \memberof), которые позволяют указать явно о них Doxygen.
Документирование перечислений
Документирование перечислений не сильно отличается от документирования других элементов. Рассмотрим пример, в котором иллюстрируется то, как можно удобно документировать их:
/// Набор возможных состояний объекта
enum States {
Disabled, ///< Указывает, что элемент недоступен для использования
Undefined, ///< Указывает, что состояние элемента неопределенно
Enabled, ///< Указывает, что элемент доступен для использования
}
То есть описание состояний указывается, собственно, после них самих при помощи краткого или подробного описания (в данном случае роли это не играет).
Результат будет иметь следующий вид:
Модули
Отдельное внимание следует обратить на создание модулей в документации, поскольку это один из наиболее удобных способов навигации по ней и действенный инструмент её структуризации. Пример хорошей группировки по модулям можете посмотреть здесь.
Далее мы кратко рассмотрим основные моменты и приведём пример, однако если вы хотите разобраться во всех тонкостях, то тогда придётся обратиться к соответствующему разделу документации.
Создание модуля
Для объявления модуля рекомендуется использовать команду \defgroup, которую необходимо заключить в документирующий блок:
\defgroup <идентификатор> (заголовок модуля)
Идентификатор модуля представляет собой уникальное слово, написанное на латинице, который впоследствии будет использован для обращения к данному модулю; заголовок модуля – это произвольное слово или предложение (желательно краткое) которое будет отображаться в документации.
Обратите внимание на то, что при описании модуля можно дополнить его кратким и подробным описанием, что позволяет раскрыть назначение того или иного модуля, например:
/*!
\defgroup maze_generation Генерация лабиринтов
\brief Данный модуль, предназначен для генерации лабиринтов.
На данный момент он поддерживает следующие алгоритмы генерации лабиринтов: Eller's algorithm, randomized Kruskal's algorithm, cellular automaton algorithm, randomized Prim's algorithm.
*/
Размещение документируемого элемента в модуле
Для того, чтобы отнести тот или иной документируемый элемент в модуль, существуют два подхода.
Первый подход – это использование команды \ingroup:
\ingroup <идентификатор> (заголовок модуля)
Его недостатком является то, что данную команду надо добавлять в документирующие блоки каждого элемента исходного кода, поскольку их в рамках одного модуля может быть достаточно много.
Поэтому возникает необходимость в другом подходе, и второй подход состоит в использовании команд начала и конца группы: @{ и @}. Следует отметить, что они используются наряду с командами \defgroup, \addtogroup и \weakgroup.
Пример использования приведён ниже:
/*! \defgroup <идентификатор> (заголовок модуля)
@{
*/
документируемые_элементы
/*! @} */
Смысл примера должен быть понятен: мы объявляем модуль, а затем добавляем к ней определенные документируемые элементы, которые обрамляются при помощи символов начала и конца модуля.
Однако, модуль должен определяться один раз, причём это объявление будет только в одном файле, а часто бывает так, что элементы одного модуля разнесены по разным файлым и потому возникает необходимость использования команды \addtogroup, которая не переопределяет группу, а добавляет к ней тот или иной элемент:
/*! \addtogroup <идентификатор> [(заголовок модуля)]
@{
*/
документируемые_элементы
/*! @} */
Название модуля указывать необязательно. Дело в том, что данная команда может быть использована как аналог команды \defgroup, и если соответствующий модуль не был определена, то она будет создана с соответствующим названием и идентификатором.
Наконец, команда \weakgroup аналогична команде \addtogroup, отличие заключается в том, что она просто имеет меньший приоритет по сравнению с ней в случае если возникают конфликты, связанные с назначение одного и того же элемента к разным модулям.
Создание подмодуля
Для создания подмодуля достаточно при его определении отнести его к тому или иному подмодулю, подобно любому другому документируемому элементу.
Пример приведён ниже:
/*! \defgroup main_module Главный модуль */
/*! \defgroup second_module Вложенный модуль
\ingroup main_module
*/
Пример создания нескольких модулей
Далее представлен подробный пример создания модуля:
Файл generate_maze.h
/*!
\defgroup generate_mazes Генерация лабиринтов
\ingroup maze
\brief Данный модуль, предназначен для генерации лабиринтов.
На данный момент он поддерживает следующие алгоритмы генерации лабиринтов: Eller's algorithm, randomized Kruskal's algorithm, cellular automaton algorithm, randomized Prim's algorithm.
*/
///@{
/*! \brief Функция генерации лабиринта на основе алгоритма Эллера
\param width, height количество клеток в высоту и ширину в лабиринте
\returns Лабиринт, представляющий собой экземпляр класса Maze с заданной шириной и высотой
*/
Maze generateEller(int width, int height);
/*! \brief Функция генерации лабиринта на основе вероятностного алгоритма Крускала
\param width, height количество клеток в высоту и ширину в лабиринте
\returns Лабиринт, представляющий собой экземпляр класса Maze с заданной шириной и высотой
*/
Maze generateKruskal(int width, int height);
/*! \brief Функция генерации лабиринта на основе вероятностного алгоритма Прима
\param width, height количество клеток в высоту и ширину в лабиринте
\returns Лабиринт, представляющий собой экземпляр класса Maze с заданной шириной и высотой
*/
Maze generatePrim(int width, int height);
/*! \brief Функция генерации лабиринта на основе клеточных автоматов
\param width, height количество клеток в высоту и ширину в лабиринте
\returns Лабиринт, представляющий собой экземпляр класса Maze с заданной шириной и высотой
*/
Maze generateCellular(int width, int height);
///@}
Файл maze.h
/*!
\defgroup maze Лабиринт
\brief Основной модуль, содержащей в себе описания лабиринтов и содержащий другие модули для работы с ними
*/
///@{
class Maze {
/* описание класса */
};
///@}
Обратите внимание на то, что вид документирующих блоков несколько изменился по сравнению с приведёнными ранее примерами, но как мы говорили ранее, принципиального значения это не играет и выбирайте тот вариант, который вам ближе.
В результате мы получим следующую документацию:
Оформления текста документации
Теперь, после того, как мы в общих чертах разобрались с тем как документировать основные элементы кода, рассмотрим то, как можно сделать документацию более наглядной, выразительной и полной.
Код внутри документации
Зачастую внутри пояснения к документации необходимо для примера добавить какой-то код, например для иллюстрации работы функции.
Команды \code и \endcode
Один из наиболее простых и универсальных способов сделать это – команды \code и \endcode, которые применяются следующим образом:
\code [ {<расширение>}]
...
\endcode
Используемый язык определяется автоматически в зависимости от расширения файла, в котором располагается документирующий блок, однако в случае, если такое поведение не соответствует ожиданиям расширение можно указать явно.
Рассмотрим пример использования:
/*!
\brief Алгоритм Евклида
\param a,b Два числа, чей наибольший делитель мы хотим найти
Данная функция реализует алгоритм Евклида, при помощи которого
находится наибольшее общее кратное у двух чисел.
Код функции выглядит следующим образом:
\code
int gcd(int a, int b) {
int r;
while (b) {
r = a % b;
a = b;
b = r;
}
return r;
}
\endcode
*/
int gcd(int a, int b);
Результат будет иметь следующий вид:
Примеры кода
Иногда удобнее приводить примеры использования кода хранить в отдельных файлах. Для этого эти файлы необходимо разместить в отдельной директории и прописать к ней путь в настройках:
EXAMPLE_PATH = путь_к_директории
Рассмотрим, некоторые способы того, как примеры кода могут быть использованы в документации.
Команда \example
Данная команда показывает, что документирующий блок относится к примеру кода.
\example <имя_файла>
Текст исходного кода будет добавлен в раздел «примеры», а исходный код примера будет проверен на наличие документированных элементов, и если таковые будут найдены, то к ним в описание будет добавлена ссылка на пример.
Файл gcd.h
/*!
\brief Алгоритм Евклида
\param a,b Два числа, чей наибольший делитель мы хотим найти
Данная функция реализует алгоритм Евклида, при помощи которого
находится наибольшее общее кратное у двух чисел.
*/
int gcd(int a, int b);
/*! \example main.cpp
Пример того, как использовать функцию
*/
Файл examples/main.cpp
В данном примере, значение EXAMPLE_PATH = examples
void main()
{
int result = gcd(52,106);
}
Команда \include
Для того, чтобы добавить в описание к документируемому элементу код примера используется команда \include, общий формат которой имеет следующий вид:
\include <имя_файла>
Она полностью копирует содержимое файла и вставляет его в документацию как блок кода (аналогично оформлению кода в блок начинающийся командой \code и заканчивающийся командой \endcode).
Команда \snippet
Команда \snippet аналогична предыдущей команде, однако она позволяет вставлять не весь файл, а его определенный фрагмент. Неудивительно, что её формат несколько другой:
\snippet <имя_файла> ( имя_фрагмента )
Для выделения определенного фрагмента кода необходимо в начале и в конце его разместить документирующий блок с указанием имени фрагмента:
/// [ имя_фрагмента ]
...
/// [ имя_фрагмента ]
Автоматическое внедрение кода документируемого объекта
Наконец, Doxygen поддерживает возможность автоматической вставки тела функций, методов, классов, структур и т.п., в их подробное описание. Для этого используется следующая опция:
INLINE_SOURCES = YES
Формулы с использованием LaTeX
Doxygen позволяет использовать TeX формулы прямо в документации, это очень удобно и результат получается весьма достойным. Однако стоит отметить, что при этом имеются ограничения: на данный момент формулы могут быть вставлены только в HTML и LaTeX документацию, но этого, как правило, вполне достаточно.
На данный момент существует два подхода к отображению формул:
- Отображение формул при помощи MathJax, для этого необходимо в файле настроек установить соответствующую опцию:
USE_MATHJAX = YES - Генерация соответствующих изображений и вставка их в документацию. Всё это будет сделано автоматически, но вам потребуется следующие инструменты: latex, dvips, gs. По умолчанию формулы отображаются именно этим способом.
Способы добавление формул в документацию
Существуют три способа добавления формул в документацию. Последовательно рассмотрим каждый из них с примерами из документации:
- Использование строчных формул, которые обрамляются в начале и в конце при помощи команды «\f$». Пример представлен ниже:
расстояние между \f$(x_1,y_1)\f$ и \f$(x_2,y_2)\f$ равно \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$.Результатом будет строка следующего вида: расстояние между
и равно - Использование выносных формул, которые начинаются на отдельной строке и центрируются. В отличие от предыдущих формул они обрамляются в начале командой «\f[«, а в конце командой «\f]». Пример представлен ниже:
\f[ |I_2|=\left| \int_{0}^T \psi(t) \left\{ u(a,t)- \int_{\gamma(t)}^a \frac{d\theta}{k(\theta,t)} \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi \right\} dt \right| \f]Результатом будет строка следующего вида:
- Существует команда «\f{environment}», где environment – это название определенного окружения в LaTeX. Она позволяет использовать указанное окружение будто бы оно было указано в обычно LaTeX документе. Пример приведён ниже:
\f{eqnarray*}{ g &=& \frac{Gm_2}{r^2} \\ &=& \frac{(6.673 \times 10^{-11}\,\mbox{m}^3\,\mbox{kg}^{-1}\, \mbox{s}^{-2})(5.9736 \times 10^{24}\,\mbox{kg})}{(6371.01\,\mbox{km})^2} \\ &=& 9.82066032\,\mbox{m/s}^2 \f}В итоге мы получим следующий результат (заметим, что окружение eqnarray* – это ненумерованное окружение для размещения нескольких формул):
и 
равно 
Пример внедрения формул в документацию
Рассмотрим конкретный пример документации с использованием формул LaTeX:
/*!
\brief Вычисление факториала числа \f$ n \f$
\param n - число, чей факториал необходимо вычислить
\return \f$ n! \f$
Данная функция вычисляет значение факториала числа \f$ n \f$, определяемое по формуле:
\f[
n! = \prod_{i = 1}^n i
\f]
*/
int factorial(int n);
Результат представлен ниже:
Кратко о Markdown
Markdown – это облегчённый язык разметки (почитать о нём можно, например, здесь, а также в специальном разделе в документации). Начиная с версии 1.8.0. Doxygen обеспечивает его пока ограниченную поддержку и он служит одним из способов оформить документацию (альтернативой могут быть, например, команды для оформления документации или HTML вставки, которые, впрочем, не универсальны).
Не хотелось бы сейчас расписывать подробности и принципы данного языка, поэтому ограничимся рассмотрением того, как данный язык позволяет «украсить» нашу документацию:
/*!
Функция генерирующая псведослучайное число
------------------------------------------
Изначально планировалось реализовать в данной функции один из следующих методов генерации псевдослучайных чисел:
- Линейный конгруэнтный метод;
- Метод Фибоначчи;
- Линейный регистр сдвига с обратной связью;
- Вихрь Мерсенна.
Но разработчики вспомнили про одну замечательную цитату:
> Есть два способа создания дизайна программы. Один из них, это сделать его настолько простым, что в нем, очевидно, не будет недостатков. Другой способ — сделать его настолько запутанным, что в нем не будет очевидных недостатков.
> — C.A. R. Hoare
И выбрали первый путь.
*/
int getRandomNumber();
Результат представлен ниже:
Подводя итоги
На этой ироничной ноте я решил остановиться. Я прекрасно понимаю, что ещё многое не было описано и затронуто, но, надеюсь, что главные свои цели статья выполнила: познакомить с понятием генератора документации, познакомиться с системой Doxygen, объяснить основные принципы и подходы к документации, а также мельком затронуть вопросы, связанные с её оформление и детализацией, подготовив задел для вашей дальнейшей работы.
Спасибо за внимание!
Литература и ссылки для дальнейшего изучения
1. Основным источником, который был использован при написании статьи была официальная документация;
2. На большое количество вопросов, связанных с Doxygen, ответы были получены здесь (там есть и создатель Doxygen).
3. Продолжение цикла: оформление внешнего вида документации, построение графов и диаграмм в Doxygen.
Резюме
Когда мы пишем код, наибольшей головной болью является руководство. Многие коды пишут определенный код при написании руководств. Doxygen в основном решает проблемы, возникающие вручную. Когда мы пишем код, мы можем преобразовывать комментарии в руководства. Graphviz в основном используется для Графический дисплей, HTML Help Help в основном используется для создания документов CHM.
1.Doxygen
Doxygen может конвертировать определенные комментарии в программе в файлы инструкций. Он может генерировать чистое справочное руководство на основе структуры самой программы, обрабатывая аннотации в программе в соответствии со спецификациями, извлекая структуру кода или с помощью автоматически генерируемых графов зависимостей, диаграмм наследования и Диаграмма сотрудничества (диаграмма сотрудничества) для визуализации взаимосвязи между документами; формат справочного документа, генерируемого Doxygen, может быть CHM, RTF, PostScript, PDF, HTML и т. Д.
2.graphviz
Graphviz (Программное обеспечение для визуализации графиков) — это набор инструментов с открытым исходным кодом, запущенный AT & T Labs для рисования графиков, описанных в сценариях языка DOT. Чтобы использовать Doxygen для создания графиков зависимостей, графиков наследования и графиков совместной работы, сначала необходимо установить программное обеспечение graphviz.
3.HTML Help WorkShop
HTML Help WorkShop от Microsoft — лучший инструмент для создания файлов CHM, который может компилировать файлы HTML для создания файлов CHM. Программное обеспечение Doxygen генерирует HTML-файлы или латексные файлы по умолчанию. Если мы хотим генерировать документы CHM через HTML, нам нужно установить программное обеспечение HTML Help WorkShop и связаться с Doxygen.
Смотрите пример визуализации.
монтаж
Загрузка Doxygen (doxygen-1.8.7-setup.exe):
http://www.stack.nl/~dimitri/doxygen/download.html
Graphviz (для Windows) скачать:
http://www.graphviz.org/Download..php
HTML Help WorkShop (1.32) скачать:
http://download.microsoft.com/download/0/a/9/0a939ef6-e31c-430f-a3df-dfae7960d564/htmlhelp.exe
Выберите метод установки программного обеспечения по умолчанию, нажимайте кнопку «Далее», пока установка не будет завершена. После установки вам необходимо связать путь установки graphviz и HTML Help WorkShop при настройке Doxygen.
конфигурация
Все наши настройки выполняются в Doxywizard, и справочное руководство генерируется при запуске Doxywizard.
1.Wizard->Project
Самое важное в Wizard-> Project — это настройка рабочего каталога, каталога исходного кода и каталога сгенерированного справочного файла.Другие имена проектов, описания проектов, версии и логотипы могут быть выбраны в соответствии с фактическими условиями.
Рабочий каталог является вновь созданным каталогом. После завершения настройки файл конфигурации может быть сохранен в этом каталоге. Каждый раз, когда файл конфигурации (.cfg) импортируется из этого каталога, генерируется файл описания ,
Каталог исходного кода и каталог конечных результатов устанавливаются при каждом запуске Doxywizard.
2.Wizard->Mode
Выберите результат оптимизации, соответствующий языку программирования, и выберите в соответствии с языком программирования.
3.Wizard->Output
Выберите формат вывода, выберите элемент (.chm) в разделе HTML, чтобы подготовиться к окончательному созданию chm. Поскольку результаты LaTeX не требуются, не выбирайте эту опцию.
4.Wizard->Diagrams
Выберите элемент инструмента точка и используйте GraphViz для рисования.
5.Expert->Project
Выберите выходной каталог, выберите выходной язык. Если в коде используются китайские комментарии, выберите китайский здесь.
Потяните ползунок вниз, и вы увидите два поля JAVADOC_AUTOBRIEF и QT_AUTOBRIEF. Если этот флажок установлен, первая строка этих двух стилей по умолчанию представляет собой простое описание, разделенное первым периодом; Если не выбран, вам нужно следовать инструкциям Doxygen @brief для стандартных комментариев.
6.Expert->Input
Измените метод кодирования ввода на метод GBK, чтобы вывод не приводил к искаженным символам из-за метода UTF-8.
Последняя и часто встречающаяся проблема заключается в том, что китайский язык в древовидной директории слева от файла CHM, созданного DoxyGen, становится искаженным. Для этого нужно только изменить тип кодировки индекса chm на GB2312. Введите GB2312 в CHM_INDEX_ENCODING HTML.
7.Expert->HTML
Проверьте элемент Generate HTMLHELP, введите имя сгенерированного CHM, введите путь hhc.exe в каталоге установки HTMLHELP WORKSHOP в HHC_LOCATION и измените метод кодирования chm на GBK, что соответствует методу кодирования ввода на шаге (6).
8.Expert->Dot
Введите путь установки GraphViz в Dot_PATH.
Вам необходимо настроить EXTRACT_ALL и LOCAL_METHODS в сборке для генерации всех переменных и функций.
9. Хранить информацию о конфигурации
Хранить информацию о конфигурации. На предыдущем шаге Doxygen был полностью настроен, и вы можете щелкнуть, чтобы запустить его в Run, но чтобы сохранить вышеуказанную информацию о конфигурации, вы можете сохранить сконфигурированный файл в файле .cfg, а затем вам нужно только открыть файл с помощью Doxygen, когда вы запускаете Doxygen. Измените входные и выходные каталоги и информацию о проекте в шаге (1) перед запуском. Файл-> Сохранить как, выберите имя, по умолчанию Doxyfile, добавьте .cfg и нажмите Сохранить. Если вам нужно изменить файл конфигурации, сохраните и замените предыдущий файл конфигурации после изменения.
10.Run->Run Doxygen
Вы можете запустить Doxygen. После запуска найдите файл index.chm в папке html в выходном каталоге, который является описанием документа входного кода.
Технические характеристики
Краткое описание спецификаций
Вкратце, блок комментариев Doxygen фактически добавляет некоторые дополнительные метки к основанию блока комментариев C и C ++, чтобы Doxygen мог его распознать и организовать в сгенерированный документ.
В каждом элементе кода может быть два типа описания: одно — краткое описание, а другое — подробное. Оба являются необязательными, но не одновременно. Краткое описание (краткое) — краткое описание в одну строку. Подробное описание (подробное) предоставляет более длинные и подробные документы.
В Doxygen блоки комментариев помечаются как подробные описания в основном следующими способами:
Стиль JavaDoc, используйте две звездочки ‘*’ в начале блока комментариев стиля C:
/**
* ...Описание ...
*/
Комментарии к коду стиля Qt, то есть добавьте восклицательный знак «!» В начале блока комментариев стиля C:
/*!
* ...Описание ...
*/
Используйте блок комментария, состоящий из более чем двух последовательных строк комментариев C ++, и пишите дополнительную косую черту или восклицательный знак в начале каждой строки комментария:
///
/// ...Описание ...
///
Аналогично, краткое описание (краткое) может быть идентифицировано несколькими способами. Рекомендуется использовать команду @brief, чтобы вызвать описание, например
/**
* @ краткий комментарий. Краткое описание.
*/
/**
* @ краткий комментарий. Краткое описание.
*/
Обратите внимание на следующие моменты:
1. Doxygen не обрабатывает все комментарии, doxygen фокусируется на комментариях, связанных со структурой программы, таких как: файл, класс, структура, функция, глобальная переменная, макрос и другие комментарии,Игнорировать комментарии к локальным переменным, коду и т. Д. В функции。
2. Комментарий должен быть написан перед соответствующей функцией или переменной. В стиле JavaDoc текст перед первым периодом «.» Автоматически воспринимается как краткий комментарий, а следующий — подробный комментарий. Вы также можете использовать пустые строки, чтобы отделить краткие комментарии от подробных комментариев. Обратите внимание, чтобы установить для JAVADOC_AUTOBRIEF или QT_AUTOBRIEF значение YES.
3. Сначала начните комментировать из файла, а затем — глобальные функции, структуры, переменные перечисления, пространство имен → классы в пространстве имен → функции-члены и переменные-члены файла.
4. Doxygen не может экспортировать документы для классов, определенных в DLL.
Общие инструкции
| инструкция | Описание |
|---|---|
| @file | Описание комментария к файлу. |
| @author | Информация автора |
| @brief | Простое описание класса или функции, например: @brief Эта функция отвечает за вывод строки сообщения об ошибке. |
| @param | В основном используется в описании функции, затем следует имя параметра, а затем описание параметра |
| @return | Опишите возвращаемое значение функции, например: @return Эта функция возвращает результат выполнения, в случае успеха возвращает TRUE, в противном случае возвращает FLASE. |
| @retval | Опишите тип возвращаемого значения |
| @note | аннотирование |
| @attention | нота |
| @warning | Предупреждение |
| @enum | Ссылка на определенное перечисление, Doxygen сгенерирует ссылку на перечисление, например: @enum CTest :: MyEnum |
| @var | Ссылка на переменную, Doxygen сгенерирует ссылку при перечислении |
| @class | Обратитесь к классу, формат: @class [] [] например: @class CTest «inc / class.h» |
| @exception | Описание возможных исключений, например: @exception При выполнении этой функции могут генерироваться исключения, выходящие за рамки |
модуль
Модули — это способ группировать вещи на отдельных страницах. Членами группы могут быть файл, пространство имен, классы, функции, переменные, перечисления, определения типов и определения, но они также могут быть другими группами.
Чтобы определить группу, \ defgroup должен быть помещен в специальный блок комментариев. Первый параметр команды должен быть меткой, однозначно идентифицирующей группу. Чтобы классифицировать сущность как члена группы, поместите команду \ ingroup перед сущностью. Вторым параметром является название группы.
Чтобы не размещать команду \ ingroup перед каждым членом в комментарии, вы можете заключить его в @ {и @}. Тег @ {@} можно разместить в комментариях группы или в отдельном блоке комментариев.
Группы маркеров, использующие эти группы, также могут быть вложенными.
Если групповой тег используется несколько раз, произойдет ошибка. Если вы не хотите, чтобы doxygen применял уникальные теги, вы можете использовать \ addtogroup вместо \ defgroup. Операция очень похожа на \ defgroup, но если группа уже определена, она добавит новый элемент в существующий комментарий по умолчанию. Заголовок группы не является обязательным для этой команды, вы также можете рассмотреть возможность его использования.
/*
* @defgroup имя модуля текст описания модуля
* @{
*/
... что определено ...
/** @} */
// В конце модуля вы можете добавить участников в группу с более подробными инструкциями в другом месте.
Если соединение (например, класс или файл) имеет несколько членов, мы обычно хотим сгруппировать их. Doxygen уже может автоматически группировать эти вещи в соответствии с типом и уровнем защиты, но вы можете подумать, что этого недостаточно, или метод по умолчанию является неправильным. Например, вы думаете, что есть разные (грамматические) типы, которые нужно сгруппировать в одну группу (семантические).
Определите группу участников следующим образом:
//@{
...
//@}
Блокировать или использовать.
/*@{*/
...
/*@}*/
Пример аннотации
1. Файл комментариев
В качестве примера напишите этот комментарий в заголовке файла кода. Вы можете видеть, что вы можете пометить некоторые текстовые имена, авторов, электронные письма, версии, даты, введения и подробные записи версий.
/**
* @file sensor.c
* @author JonesLee
* @email [email protected]
* @version V4.01
* @date 07-DEC-2017
* @license GNU General Public License (GPL)
* @brief Universal Synchronous/Asynchronous Receiver/Transmitter
* @detail detail
* @attention
* This file is part of OST. \n
* This program is free software; you can redistribute it and/or modify \n
* it under the terms of the GNU General Public License version 3 as \n
* published by the Free Software Foundation. \n
* You should have received a copy of the GNU General Public License \n
* along with OST. If not, see <http://www.gnu.org/licenses/>. \n
* Unless required by applicable law or agreed to in writing, software \n
* distributed under the License is distributed on an "AS IS" BASIS, \n
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. \n
* See the License for the specific language governing permissions and \n
* limitations under the License. \n
* \n
* @htmlonly
* <span style="font-weight: bold">History</span>
* @endhtmlonly
* Version|Auther|Date|Describe
* ------|----|------|--------
* V3.3|Jones Lee|07-DEC-2017|Create File
* <h2><center>©COPYRIGHT 2017 WELLCASA All Rights Reserved.</center></h2>
*/
После компиляции с помощью doxygen откройте веб-страницу для отображения следующего: Ниже приведено имя, а значение не объяснено.
2. Класс и комментарии членов
/**
* @class <class‐name> [header‐file] [<header‐name]
* @brief brief description
* @author <list of authors>
* @note
* detailed description
*/
Если комментарии к документам делаются для членов файлов, структур, объединений, классов или перечислений, и комментарии должны добавляться среди членов, и эти комментарии часто следуют за каждым членом. Для этого вы можете использовать знак «<» в разделе комментариев.
int var; /**< Detailed description after the member */
Пример аннотации для класса следующий:
class Test
{
public:
/** @brief A enum, with inline docs */
enum TEnum
{
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
*enumPtr, /**< enum pointer. */
enumVar; /**< enum variable. */
/** @brief A constructor. */
Test();
/** @brief A destructor. */
~Test();
/** @brief a normal member taking two arguments and returning an integer value. */
int testMe(int a,const char *s);
/** @brief A pure virtual member.
* @param[in] c1 the first argument.
* @param[in] c2 the second argument.
* @see testMe()
3. Функциональные комментарии
Посмотрите прямо на случай следующим образом, посмотрите, что вы знаете, поэтому я не буду повторять это.
/**
* @brief can send the message
* @param[in] canx : The Number of CAN
* @param[in] id : the can id
* @param[in] p : the data will be sent
* @param[in] size : the data size
* @param[in] is_check_send_time : is need check out the time out
* @note Notice that the size of the size is smaller than the size of the buffer.
* @return
* +1 Send successfully \n
* -1 input parameter error \n
* -2 canx initialize error \n
* -3 canx time out error \n
* @par Sample
* @code
* u8 p[8] = {0};
* res_ res = 0;
* res = can_send_msg(CAN1,1,p,0x11,8,1);
* @endcode
*/
extern s32 can_send_msg(const CAN_TypeDef * canx,
const u32 id,
const u8 *p,
const u8 size,
const u8 is_check_send_time);
После открытия веб-страницы аннотации она отображается следующим образом.
4. Перечень примечаний
Посмотрите прямо на случай следующим образом, посмотрите, что вы знаете, поэтому я не буду повторять это.
/** bool */
typedef enum
{
false = 0, /**< FALSE 0 */
true = 1 /**< TRUE 1 */
}bool;
5. Глобальные переменные и макросы
6. Примечания к модулю
Группа определяет приоритет команды (от высокого до низкого): \ ingroup, \ defgroup, \ addtogroup, \ weakgroup. И \ stronggroup похожа на \ addtogroup с низким приоритетом. Он предназначен для реализации «ленивого» метода определения группы: вы можете использовать высокий приоритет для определения структуры в файле .h и использовать \ stronggroup в файле .cpp, чтобы иерархическая структура в файле .h не повторялась.
При фактическом использовании мы можем видеть конкретную веб-страницу, показанную ниже.
На рисунке под BSP находится светодиодный модуль, который представляет собой файл драйвера. Конкретный код выглядит следующим образом, чтобы показать эффект, я удалил комментарий функции.
/**
* @file led.h
* @author JonesLee
* @email [email protected]
* @version V4.01
* @date 07-DEC-2017
* @license GNU General Public License (GPL)
* @brief Controller Area Network
* @detail detail
* @attention
* This file is part of OST. \n
* This program is free software; you can redistribute it and/or modify \n
* it under the terms of the GNU General Public License version 3 as \n
* published by the Free Software Foundation. \n
* You should have received a copy of the GNU General Public License \n
* along with OST. If not, see <http://www.gnu.org/licenses/>. \n
* Unless required by applicable law or agreed to in writing, software \n
* distributed under the License is distributed on an "AS IS" BASIS, \n
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. \n
* See the License for the specific language governing permissions and \n
* limitations under the License. \n
* \n
* @htmlonly
* <span style="font-weight: bold">History</span>
* @endhtmlonly
* Version|Auther|Date|Describe
* ------|----|------|--------
* V3.3|Jones Lee|07-DEC-2017|Create File
* <h2><center>©COPYRIGHT 2017 WELLCASA All Rights Reserved.</center></h2>
*/
/** @addtogroup BSP
* @{
*/
/**
* @brief Light Emitting Diode
*/
/** @addtogroup LED
* @{
*/
#ifndef __LED_H__
#define __LED_H__
#ifdef __cplusplus
extern "C" {
#endif
#include "bsp.h"
extern s32 led_init(Led_TypeDef led);
extern s32 led_config(void);
extern s32 led_on(Led_TypeDef led);
extern s32 led_off(Led_TypeDef led);
extern s32 led_toggle(Led_TypeDef led);
#ifdef __cplusplus
}
#endif
#endif /*__LED_H__ */
/**
* @}
*/
/**
* @}
*/
/******************* (C)COPYRIGHT 2017 WELLCASA All Rights Reserved. *****END OF FILE****/
Выше было объяснено, что это язык C, а язык C. не имеет наследования. Иногда необходимо показать наследование в C ++. Как показано
1.
Автоматизация процесса документирования
Наиболее полной и согласованной получается документация при автоматизации процесса докумен-
тирования. Автоматизированное документирование — одна из самых важных сторон разработки про-
граммного кода. Идея автоматизированного документирования заключается в том, что в исходном коде
пишутся комментарии в специальном формате. Далее запускается специальная утилита, которая разбира-
ет исходный код, вытаскивая комментарии и объединяя их в единый структурированный документ. Таким
образом, с плеч программиста снимается вся черновая работа по созданию программной документации.
Кроме того, такой способ документирования позволяет более строго контролировать версии программ-
ного кода и документации, поскольку при изменении программного кода программист должен изменять
расположенные рядом комментарии.
Для документирования программного кода используют программы-генераторы, сканирующие файлы
проекта в поисках комментариев. Без комментариев даже небольшую программу трудно понять не только
постороннему программисту, но и самому автору.
Многие среды разработки (Zend, Visual Studio, Netbeans) уже включают в себя средства документиро-
вания, но никакого общего стандарта до сих пор нет. В своём большинстве, цель генераторов — составить
нечто типа энциклопедии всех функций, классов, объектов, иерархий классов, связей между файлами,
используемые компоненты и третьи программные продукты.
Генераторы можно условно разделить на:
• Универсальные
—
Doxygen
—
Natural Docs
На выходе — HTML.
—
AsciDoc
(GNU GPLv2) На выходе — HTML(4,5), XHTML, DocBook, L
A
TEX, PDF, EPUB, DVI,
PS, man, HTML Help, txt.
—
Doc-O-Matic
для C/C++, C#, Delphi, VB.NET, IDL, Java, PHP, JavaScript, ASPX, JSP, MatLab.
Doc-O-Matic ships with link databases for Microsoft Visual Studio 2010, 2008, 2005, MSDN,
Embarcadero RAD Studio XE, 2010 as well as previous CodeGear and Borland Delphi versions of
Delphi and C++Builder. V7 — $49.
Специфичные
—
javadoc
(Free) для Java.
—
phpDocumentor
(Open Source) для PHP.
—
Docutils
(Open Source) для Python.
—
NDoc
,
Sandcastle
,
GhostDoc
для .NET.
—
PasDoc
(GNU GPLv2) для Pascal (Object Pascal) На выходе — HTML, HtmlHelp, L
A
TEX, . . . .
Генераторы, как правило, по-своему хранят данные и комментарии, завися от языка, однако последние
тенденции, например в Visual Studio, показывают популяризацию xml. DocBook — одна из предлагаемых
универсальных схем.
2.
Doxygen
Doxygen — мощная и распространённая утилита для документирования программного кода, написан-
ного на C, C++, Objective-C, Java, Python, IDL (Corba и Microsoft) и некоторых версий PHP, C#, и D.
Выходная документация представляет собой файлы в формате HTML, XML, L
A
TEX (в частности, для даль-
нейшего создания PDF-файлов), RTF, справочного руководства в стиле кроссплатформенной библиотеки
Qt, справочного руководства в стиле Unix — man и т. д.
Даже, если не оформалять специальным образом исходные тексты, Doxygen сгенерирует из них замеча-
тельные справочники программного интрефейса приложения. В выходной документ могут быть включены
разделы с описанием используемых пространств имён, классов, файлов и их указатели на соответствую-
щие разделы. В случае использования пакета визуализации графов — Graphviz, описание классов может
сопровождаться диаграммами UML.
Распространяется по лицензии GNU GPL.
Существует два вида комментариев:
c
О. В. Журенков
АлтГУ, г. Барнаул -2018
2
Комментарии для автоматизированного документирования исходного кода. Эти комментарии
оформляются с помощью специальных форматов (doxygen, javadoc, MS XML Documentation Comments).
Комментарии исходного кода — сопровождающие исходный код, объясняющие его работу, раскры-
вающие непонятные и сомнительные моменты.
В отличие от комментариев для автоматизированного документирования, эти комментарии исполь-
зуются в любом программном коде. Стоимость владения исходным кодом уменьшается прямо про-
порционально количеству и качеству таких комментариев. Это связано с тем, что хорошо структу-
рированный и комментированный код легче поддерживается и сопровождается. То есть программи-
стам просто требуется меньше времени для того, чтобы разобраться с ним. Для анализа качества
исходного кода можно использовать специализированные инструменты (например, together), кото-
рые подсчитывают различные метрики кода, описывающие его качество.
Doxygen позволяет из комментариев кода, записанных в специальном формате, генерировать докумен-
ты HTML, L
A
TEX, RTF, PDF с ссылками, диаграммами классов и прочими удобствами.
В Doxygen существуют несколько вариантов комментариев для автоматизированного документирова-
ния:
1. блочный стиль JavaDoc
/**
комментарий
*/
2. блочный стиль Qt
/*!
комментарий
*/
3. строчный стиль C++
/// комментарий
4. строчный стиль C++
//! комментарий
Всё, что написано внутри комментариев, оформленных таким образом, выносится в документацию. Для
единообразия лучше использовать /// для коротких комментариев и /** */ для длинных.
Служебные слова
В Doxygen есть служебные слова, которые задают правила отображения частей документации (выделе-
ние в отдельный раздел, специальное форматирование и шрифт для выделения примера кода, вынесение
текста на заглавную страницу и т.п.).
Автор — @author имя
Текст на главной странице — @mainpage
Создание новой страницы — @page идентификатор название
Создание раздела — @section идентификатор название
Вставка примера кода — @code текст программы @endcode
@page pagereq Требования к системе
@section common Общие требования
Заметка — @note
c
О. В. Журенков
АлтГУ, г. Барнаул -2018
3
Предупреждение — @warning
Описание к файлу — @file
Краткое описание — @brief Можно настроить файл опций таким образом, чтобы в краткое описание
выносилось первое предложение до точки подробного описания (по умолчанию описание считается
подробным). Для этого нужно включить опцию JAVADOC_AUTOBRIEF — в утилите doxywizard
она находится на первой странице.
Подробное описание — @full
Именованная группа — @name имя . После этого группа в скобках @{ . . . @}
Внутри парного тега \f можно задавать формулу в нотации L
A
TEX. Этот тег будет проигнорирован,
если в качестве выходного формата используется не L
A
TEX. [формулы в Doxygen]
Расстояние между \f$(x_1,y_1)\f$ и \f$(x_2,y_2)\f$
вычисляется, как \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$.
Расстояние между (x
1
, y
1
) и (x
2
, y
2
) вычисляется, как
p(x
2
− x
1
)
2
+ (y
2
− y
1
)
2
.
Документирование функций
@function имя-функции
[функции в Doxygen]
/**
@function MyFunction
Тестовая функция, имеет два входных параметра.
@param in\_Parameter1 — параметр, отвечающий за что-то
@param out\_Parameter2 — параметр, отвечающий за что-то ещё
@return true если всё хорошо, false если всё плохо
*/
bool MyFunction (int in\_Parameter1, std::string out\_Parameter2);
Синтаксис
имеет следующий вид:
1. Для генерации шаблона конфигурационного файла
doxygen [-s] -g [configName]
If — is used for configName doxygen will write to standard output.
2. Для обновления шаблона конфигурационного файла
doxygen [-s] -u [configName]
3. Генерация документации на основе конфигурационного файла
doxygen [configName]
If — is used for configName doxygen will read from standard input.
4. Для создания файла шаблона управления макетом при генерации документации
doxygen -l layoutFileName.xml
5. Для генерации файла документации с заданным расширением (на примере .rtf)
RTF:
doxygen -e rtf extensionsFile
6. Для создания шаблона стиля для RTF, HTML или L
A
TEX
c
О. В. Журенков
АлтГУ, г. Барнаул -2018
4
RTF:
doxygen -w rtf styleSheetFile
HTML:
doxygen -w html headerF footerF styleSheetF [configFile]
LaTeX: doxygen -w latex headerF footerF styleSheetF [configFile]
If -s is specified the comments in the config file will be omitted. If configName is omitted ‘Doxyfile’ will be used
as a default.
Файл настроек можно редактировать в любом текстовом редакторе или с помощью специальных ути-
лит с графическим интерфейсом. Одна из них, Doxywizard, поставляется вместе с Doxygen.
Схема работы Doxygen (совместно с Doxywizard) представлена на рис.
1
.
Рис. 1. Информационные потоки Doxygen
Manual for version 1.8.1Written by Dimitri van Heesch©1997-2012ContentsIUser Manual51Installation71.1Compiling from source on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71.2Installing the binaries on UNIX . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .81.3Known compilation problems for UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91.4Compiling from source on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111.5Installing the binaries on Windows . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . .111.6Tools used to develop doxygen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122Getting Started132.1Step 0: Check if doxygen supports your programming language . . . . . . . . . . . . . . . . . . .
.142.2Step 1: Creating a configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142.3Step 2: Running doxygen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152.3.1HTML output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162.3.2LaTeX output . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162.3.3RTF output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162.3.4XML output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .162.3.5Man page output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16Step 3: Documenting the sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172.433.13.2Documenting the code19Special comment blocks . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193.1.119Comment blocks for C-like languages (C/C++/C#/Objective-C/PHP/Java) . . . . . . . . . . .3.1.1.1Putting documentation after members . . . . . . . . . . . . . . . . . . . . . . .213.1.1.2Examples223.1.1.3Documentation at other places.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . .243.1.2Comment blocks in Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263.1.3Comment blocks in VHDL . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . .273.1.4Comment blocks in Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .283.1.5Comment blocks in Tcl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29Anatomy of a comment block . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . .30444.1CONTENTSMarkdown33Standard Markdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .334.1.1Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . .334.1.2Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .334.1.3Block quotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .344.1.4Lists . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .344.1.5Code Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .344.1.6Horizontal Rulers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354.1.7Emphasis . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354.1.8code spans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354.1.9Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354.1.9.1Inline Links . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354.1.9.2Reference Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .364.1.11 Automatic Linking . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37Markdown Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .374.2.1Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . .374.2.2Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .374.2.3Fenced Code Blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .374.2.4Header Id Attributes . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .38Doxygen specifics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384.3.1Including Markdown files as pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384.3.2Treatment of HTML blocks. . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .394.3.3Code Block Indentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .394.3.4Emphasis limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .404.3.5Code Spans Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .404.3.6Lists Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .404.3.7Use of asterisks . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . .404.3.8Limits on markup scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41Debugging of problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .414.1.10 Images4.24.34.45Grouping435.1Modules . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .435.2Member Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .455.3Subpaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .476Including Formulas497Graphs and diagrams518Preprocessing55Generated by DoxygenCONTENTS95Automatic link generation599.1Links to web pages and mail addresses . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .599.2Links to classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .599.3Links to files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .599.4Links to functions.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .599.5Links to other members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .609.6typedefs . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .6210 Output Formats6311 Searching6512 Customizing the Output6712.1Minor Tweaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6712.1.1 Overall Color. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . .6712.1.2 Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6712.1.3 Dynamic Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6812.1.4 Header, Footer, and Stylesheet changes . . . . . . . . . . . . . . . . . . .
. . . . . . . . .6812.2Changing the layout of pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6912.3Using the XML output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7113 Custom Commands7313.1Simple aliases . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7313.2Aliases with arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7313.3Nesting custom command . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .7414 Link to external documentation7515 Frequently Asked Questions7716 Troubleshooting81II83Reference Manual17 Features8518 Doxygen usage8718.187Fine-tuning the output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .19 Doxywizard usage8920 Configuration9120.1Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9120.2Project related options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.93Generated by Doxygen6CONTENTS20.3Build related options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9620.4Options related to warning and progress messages . . . . . . . . . . . . . . . . . . . . . . . . . . .9920.5Input related options . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .9920.6Source browsing related options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10120.7Alphabetical index options . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 10120.8HTML related options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10220.9LaTeX related options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10620.10 RTF related options . . . . . . . . . .