Автодокументирование с помощью Doxygen¶

• Table of contents
• Автодокументирование с помощью Doxygen
  • Установка
  • Создание и настройка проекта
  • Структура документации
  • Интеграция в MSVC
    • Комментирование класса
    • Комментирование энума
    • Объявление секции
    • Объявление страницы

Установка¶

1. Скачать с сайта http://www.doxygen.org
2. Запустить установку
   {{Image("install-01.png"," nolink")}}
   {{Image("install-02.png"," nolink")}}
   {{Image("install-03.png"," nolink")}}
3. После установки doxygen пропишет себя в пути и его можно будет использовать из командной строки.

Создание и настройка проекта¶

Для создания проекта удобно использовать поставляемую вместе с doxygen-ом оболочку - DoxygenGUI.
{{Image("doxygen-gui.png"," nolink")}}
В п.1 указывается начальная директория проекта (если в файле проекта она пустая - за директорию проекта принимается путь по которому лежал файл проекта), в п.2 указывается название проекта, в п.3 указывается директория с исходными кодами (можно указывать относительно начальной директории проекта).
{{Image("doxygen-gui2.png"," nolink")}}
В п.1 необходимо выбрать язык, для которого будет производиться оптимизация документации.
{{Image("doxygen-gui3.png"," nolink")}}
При настройке вывода doxygen-а необходимо выбрать HTML с панелью навигации и функциями поиска (п.1 и п.2). Остальные опции - по необходимости. 1.
{{Image("doxygen-gui4.png"," nolink")}}
В настройке диаграмм использовать встроенный генератор диаграмм
{{Image("doxygen-gui-expert1.png"," nolink")}}
Расширенных настройках проекта (вкладка Expert) необходимо указать язык выходных файлов (параметр OUTPUT_LANGUAGE)
{{Image("doxygen-gui-expert2.png"," nolink")}}
В настройках входных файлов необходимо указать кодировку "Windows-1251" в поле "INPUT_ENCODING", в список игнорируемых файлов "EXCLUDE" добавить таковые (например "stdafx.h"), в поле "FILE_PATTENTS" добавить маску обрабатываемых файлов.
{{Image("doxygen-gui-expert3.png"," nolink")}}
В настройках "HTML" в поле "HTML_OUTPUT" необходимо указать папку для выходных файлов.

Структура документации¶

Doxygen позволяет как документировать конструкции языка переменные функции, классы, энумы и т.п., так и создавать вербальное описание проекта с разбивкой на модули, страницы с возможностью использования ссылок между элементами документации, группировкой по какому-либо признаку.
Часть признаков группировки, относящихся особенностям языка программирования, реализуется автоматически, например, doxygen сам создаст алфавитный список классов, списки файлов проекта, списки энумов и наймспейсов, создаст дерево объектво и т.п.

Существует так называемая "главная страница" (mainpage), которая является фактически первой страницей полученной с помощью Doxygen-а документации.
Для структурирования и группировки информации применяются страницы (page), подстраницы (subpage), группы (addtogroup).
Для указания связей между объектами применяются ссылки (ref) и указатели "смотри также" (sa)

Страница - это самостоятельное текстовое описание модуля может содержать в своем составе html код.
Группа - объединение описаний нескольких комментируемых конструкций языка в один модуль.

Управляющие символы и ключевые слова
Для выделения элементов относящихся к документации используются следующие варианты комментариев:

/**
 *  ... text ... 
 */

/*!
 *  ... text ... 
 */

/*!
    ... text ...
*/

/// 
/// ... text ... 
///

//! 
//! ... text ...
//!

Таким образом, к документации относится все, что заключено в: "/ /", "/! */" или начинается с "///" или "//!".

Ключевые слова, применяемые Doxygen-ом используются для спецификации цели следующего за ними комментария.
Такие "ключевые слова" должны предварительно выделяться либо символом "@" либо символом "\".
Например:

/*! 
 * @class CMyClass
 * Описание моего класса...
* @brief Сокращенное описание моего класса
 */

или

/*! 
 * \class CMyClass
 * Описание моего класса...
* \brief Сокращенное описание моего класса
 */

Кроме того, если комментарий вставляется непосредственно перед комментируемым объектом, то можно не указывать тип комментируемого объекта.
Например:

//! Описание моего класса
calss CMyClass
{
}

Существует возможность разместить комментарий прямо на одной строке с комментируемым объектом. В этом случае в конец начальной последовательности комментария добавляется символ "<" ("//!< …" или "///< …" или "/!< …/ или "/< … */").
Например:

class CMyClass //!< Описание моего класса
{
}

Для определения секций и группировки комментариев существуют следующие ключевые слова:
1. defgroup <имя группы> [<описание группы>] - объявляет новую группу
2. addgroup <имя группы> [<описание группы>] - создает группу, если группа отсутствовала
3. ingroup <имя группы> [<имя группы>…] - добавляет комментируемый объект в указанную(ые) группу(ы)

Для выделения нескольких комментируемых объектов, после ключевых слов "defgroup" или "addgroup" должны следовать метки начала и конца группы. Это - ключевые слова "{" и "}" соответственно.

Например:

//! @addgroup group1 Описание группы N1
//! @{ 
...
//! @}

Интеграция в MSVC¶

Чтобы документация строилась автоматически в VS необходимо добавить в проект файл проекта doxygen, указать что этот файл должен быть обработан "Custom Build Tool-ом".

{{Image("doxygen-msvc1.png"," nolink")}}

За тем необходимо указать командную строку (Command Line) вида: "doxygen <имя файла проекта doxgen-а>", указать путь к главному файлу получаемой документации (Outputs) и дополнительные зависимости (ключевые файлы документации, изменение которых будет приводить к перестроению документации).

{{Image("doxygen-msvc2.png"," nolink")}}

Примеры
h3. Комментирование функции

/*!
* @fn MyFunction
* @brief Краткое описание функции
* Развернутое описание функции
* @param int [in] arg1 описание первого аргумента
* @return int описание возвращаемого значения
 */
int MyFunction(const int arg1, int& arg2)
{
}

//! Описание функции \return Описание возвращаемого значения
int MyFunction(
    const int arg1 /*!< [in] описание первого аргумента */,
    int& arg2      /*!< [in,out] описание второго аргумента */)
{
}

Комментирование класса¶

/**
* \class CMyClass 
* Описание класса... ну очень подробное...
* \brief Коротенькое описание класса
 **/
class CMyClass
{
}

//! Описание класса
class CMyClass
{
}

class CMyClass //!< Описание класса
{
}

Комментирование энума¶

/*!
* \enum EMyEnum
* Подробнейшее описание энума
* \brief Короткое описание энума
 */
enum EMyEnum
{
    //! описание значения энума N1
    eValue1,
    //! описание значения энума N2
    eValue2,
}

enum EMyEnum //!< Описание энума
{
    eValue1, /*!< Описание значения N1 энума */
    eValue2, /*!< Описание значения N2 энума */
}

Объявление секции¶

//! @addsection SectionN1 Описание секции N1
//!@{
...
//!@}

Объявление страницы¶

//! @mainpage Начальная страница
//! @ref Page1
//! @ref Page2
/*! 
    Много текста
*/
//@sa ClassName
//@sa SectionName

//! @page Page1 Страница N1
//! @ref Page2
/*! 
    Много текста
*/
//@sa ClassName
//@sa SectionName