Многострочный блок
любой блок – это комментарий, оформленный специальным образом. Поэтому необходимо определить каким таким «специальным образом». Вообще, существует целый ряд способов для описания многострочного блока, и выбор конкретного способа зависит от ваших предпочтений:
Qt стиль, в котором в начале вместо второй звёздочки ставится восклицательный знак:
/*!
*... первая строчка...
*... вторая строчка...
*/
При этом текст, написанный в таком комментарии, относится к подробному описанию.
Для указания краткого описания может быть использована команда \brief. Указанный после команды текст, вплоть до конца параграфа будет относится к краткому описания, и для отделения подробного описания и краткого описания используется пустая строка.
/*!
\brief Краткое описание и
его продолжение.
Подробное описание
*/
Однострочный блок
Для описания однострочного блока опять же существует целый ряд способов оформления, рассмотрим два из них:
Можно использовать специальный комментарий в C++ стиле:
/// Краткое описание
Можно использовать аналогичный предыдущему комментарий, только вместо дополнительного слеша в нем ставится восклицательный знак:
//! Краткое описание
При этом хотелось бы обратить внимание на два момента:
1) Для указания подробного описания в однострочном документирующем блоке может быть использована команда \details:
/// \details Подробное описание
2) Документирующие блоки, следующие друг за другом, объединяются в один (причем вне зависимости от используемого стиля и того, являются они многострочными или однострочными).
Например следующие два способа документирования дадут один и тот же результат:
/// \brief Краткое описание
/// \details Подробное описание
///Краткое описание
/*!
Подробное описание
*/
Размещение документирующего блока после элемента
Во всех предыдущих примерах подразумевалось, что документирующий блок предварял документируемый элемент, но иногда бывают ситуации, когда удобнее разместить его после документируемого элемента. Для этого необходимо в блок добавить маркер "<", как в примере ниже:
int variable; ///< Краткое описание
Пример документации
Теперь рассмотрим то, как это будет выглядеть на практике. Ниже представлен документированный код некоторого класса в соответствии с теми правилами, которые мы рассматривали ранее.
/*!
\brief Родительский класс, не несущий никакой смысловой нагрузки
Данный класс имеет только одну простую цель: проиллюстрировать то,
как Doxygen документирует наследование
*/
class Parent {
public:
Parent();
~Parent();
};
Команды
С несколькими из команд в 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 Заголовочный файл с описанием классов
Данный файл содержит в себе определения основных
классов, используемых в демонстрационной программе
*/
Документирование функций и методов
При документировании функций и методов чаще всего необходимо указать входные параметры, возвращаемое функцией значение, а также возможные исключения. Рассмотрим последовательно соответствующие команды.
Параметры
Для указания параметров необходимо использовать команду \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);
Оформления текста документации
Теперь, после того, как мы в общих чертах разобрались с тем как документировать основные элементы кода, рассмотрим то, как можно сделать документацию более наглядной, выразительной и полной.
Код внутри документации
Зачастую внутри пояснения к документации необходимо для примера добавить какой-то код, например для иллюстрации работы функции.
Команды \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);