Использование Doxygen для документирования кода

• Источник

Использование Doxygen

Использовать Doxygen просто – для этого надо просто запустить программу указав ей путь к файлу с настройками. Файл с настройками представляет собой простой текстовой файл, который можно редактировать как в текстовом редакторе, так и с помощью специальных программ, например Doxygate.

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

Я предпочитаю редактировать этот файл вручную, тем более, что его достаточно настроить один раз под свои потребности и затем в новых проектах изменять одну строку – имя проекта. В конце заметки будет представлен используемый мной конфигурационный файл.

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

Doxygen поддерживает несколько стилей комментариев. Я придерживаюсь следующего:

/** Комментарии */

Обратите внимание, что последовательность символов /** сообщает программе, что начинается комментарий предназначенный для нее. Начиная с этого места и до завершающих символов */ следуют комментарии.

Есть несколько директив, которые помогают Doxygen составить грамотную документацию. Вот основные:

@brief	Краткое описание комментируемой сущности. Пример: @brief Функция для поиска пользователя в базе данных
@detailed	Подробное описание сущности, то что будет показано, когда вы нажмете в документации рядом с коротким описанием ссылку "Подробней". На мой взгляд использоваться должно как можно реже, в силу того, что короткое описание должно точно отражать идею использования сущности, а использование ее не должно сопровождаться неожиданными предусловиями. Пример: @detailed Данная функция делает выборку из базы данных по имени пользователя и возвращает структуру с информацией о нем. Ожидается, что соединение с базой данных установлено и пользователь существует
@param	Параметры передаваемые функции. Пример: @param name Имя пользователя
@return	Возвращаемое функцией значение. Пример: @return Информация о пользователе
@throw	Исключения выбрасываемые функцией. Пример: @throw DatabaseError Если произошла ошибка при подключении к базе данных

Пример комментариев для класса:

/** @brief Класс для работы с базой данных @detailed Осуществляет подключение к базе при создании  и закрывает соединение при уничтожении */
class Database
{
public:
/** @brief Конструктор @param connectionString Строка подключения к базе данных @throw ConnectionError Если подключение не удалось */
	explicit Database(const std::string& connectionString);
/** @brief Поиск пользователя в базе данных @detailed Данная функция делает выборку из базы данных  по имени пользователя и возвращает структуру с информацией  о нем. Ожидается, что соединение с базой данных установлено  и пользователь существует @param name Имя пользователя @return Информация о пользователе @throw DatabaseError Если произошла ошибка при подключении  к базе данных @throw InvalidRequest Если пользоваделя в базе не существует */
	CustomerPtr GetCustomer(const std::string& name);
};

Этого достаточно для 99% кода, но остается вопрос комментирования на уровне проекта, а не файла. Для этого служат следующие директивы:

@mainpage	Основная страница проекта, то с чего начинается просмотр документации. Пример: @mainpage Приложение для учета пользователей
@page	Дополнительные страницы проекта. Я рассматриваю их как логически обособленные части проекта. Пример: @page Database Database Утилиты для работы с базой данных
@ref	Ссылки на страницы проекта, с их помощью можно организовать например ссылки с главной страницы проекта на страницы подпроектов. Пример: @ref Database Утилиты для работы с базой данных

Для организации четкой структуры я рекомендую в каждом подпроекте создавать файл description.h в котором будет директива @page, описание для чего нужен этот подпроект и принципы работы с ним.

В свою очередь в корне проекта я также создаю файл description.h в котором немного рассказано о проекте в целом и приведены ссылки на его части:

/** @mainpage Приложение для учета пользователей Состоит из следующих частей: - @ref Database Утилиты для работы с базой данных */

Чтобы привести фрагмент кода (например пример работы с классом) используется конструкция @code – @endcode:

/** Пример использования Foo: @code Foo f(); f.Run(); @endcode */

Списки можно создавать с помощью символа - (минус). Пример:

/** Список: - Первый пункт - Второй пункт */

Перечисления я оформляю так:

/** @brief Режимы устройства */
enum Mode
{
	Mode_On,	/**< Включено */
	Mode_Off	/**< Выключено */
};

В большинстве случаев приведенных директив достаточно, с полным списком вы можете ознакомиться в руководстве.

Ложка дегтя

Обратите внимание! Очень ВАЖНО перед объявлением пространства имен повторять его имя в комментарии Doxygen. Похоже на баг (версия 1.6.2), но без этого содержимое пространства не попадет в документацию. Пример:

/** namespace A @brief Пространство имен A */
namespace A
{
}

Символ @ в конструкции namespace отсутствует!

Файл с настройками Doxygen

Как уже упоминалось, для работы Doxygen нужен файл с настройками. Программа умеет создавать файл с параметрами по умолчанию:

doxygen -g

После этого будет сгенерирован файл с именем Doxyfile содержащий настройки по умолчанию. Вы можете отредактировать его под свои нужды, что сделать довольно просто благодаря содержащимся в нем пояснениям.

Рассмотрю некоторые из пунктов которые я изменяю:

PROJECT_NAME	Имя проекта.
QUIET	Допустимые значения YES и NO. Я ставлю YES, для того чтобы предупреждения не терялись среди обилия информации о работе программы.
WARN_NO_PARAMDOC	YES для вывода предупреждений о недокументированных аргументах функции.
INPUT	Путь к анализируемому коду. Я рекомендую в корне проекта создать директорию docs содержащую Doxyfile с настройками, в таком случае значение этого параметра будет ../
FILE_PATTERNS	Шаблон для имени анализируемых файлов. Поскольку документироваться должны только открытые интерфейсы, то очевидно, что следует анализировать только заголовочные файлы: *.h
RECURSIVE	Рекурсивно анализировать файлы в поддиректориях – YES.
EXCLUDE_PATTERNS	Исключение из анализа директорий соответствующих маске. Пример: EXCLUDE_PATTERNS = */.svn/* */build/* */tests/* */sources/*
HAVE_DOT	YES, если установлен Graphviz и требуется визуализация связей.

Очень разумно будет один раз написать свою конфигурацию для Doxygen и в новых проектах менять лишь один параметр – PROJECT_NAME.