Личный опыт разработки ПО

Написание документации к коду задача не самая простая и уж точно не самая приятная, но к счастью существуют инструменты которые могут существенно упростить эту процедуру. Для этих целей я использую инструмент Doxygen и именно о нем пойдет речь.

Что такое Doxygen?

Doxygen – это кроссплатформенная система документирования кода с поддержкой языков C++, C, Java, Objective-C, PHP, C# (список можно уточнить на сайте проекта).

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

Doxygen умеет анализировать исходный код проекта и создавать удобную документацию в формате HTML, Latex, RTF, XML, man, CHM.

Общие соображения

1. Написание документации должно быть максимально простым, чтобы разработчики не "забывали" это делать. Отсюда вывод, что сложность форматирования комментариев должна быть минимальной.

   Хорошо:

   namespace A { /** Имя класса   Описание класса */ class B { }; }

   Плохо:

   namespace A { /** * Имя класса * * Описание класса */ class B { }; }

   Почему второй вариант хуже? Очевидно, из-за необходимости выравнивать комментарии на одном уровне с комментируемой сущностью, а также из-за избыточных символов *. Это может показаться надуманным, но при написании комментариев из нескольких строк проблема проявляется, а при поддержке кода и вовсе становится кошмаром. Вы можете возразить, что подобный стиль делает код "рваным", но в любом случае комментирование интерфейсов делает код менее читаемым. К счастью все современные редакторы кода позволяют легко свернуть блоки с комментариями, что позволит взглянуть на код без помех.

2. Много документации – плохо, так как мало кто будет читать длинные мануалы. Из этого следует, что документированы должны быть только открытые (public) и защищенные (protected) интерфейсы. Закрытые (private) интерфейсы – часть внутренней реализации и не должны быть в руководстве.

Что нам понадобится?

Нам понадобится сделать две вещи:

1. Установить Doxygen, если он еще не установлен.
2. Установить Graphviz. Graphviz – это свободно распространяемый пакет утилит для визуализации данных. Нам он нужен для того, чтобы Doxygen мог показать в документации отношения наследования, графы вызовов и прочую информацию в виде наглядных изображений.

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

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

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

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

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

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

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

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

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

@brief Функция для поиска пользователя в базе данных

@detailed Данная функция делает выборку из базы данных 
по имени пользователя и возвращает структуру с информацией 
о нем. Ожидается, что соединение с базой данных установлено 
и пользователь существует

@param name Имя пользователя

@return Информация о пользователе

@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 Приложение для учета пользователей

@page Database Database
Утилиты для работы с базой данных

@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 содержащий настройки по умолчанию. Вы можете отредактировать его под свои нужды, что сделать довольно просто благодаря содержащимся в нем пояснениям.

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

EXCLUDE_PATTERNS = */.svn/* */build/* */tests/* */sources/*

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

Мой конфигурационный файл приведен чуть ниже. Он настроен на вывод предупреждений если не были документированы какие-либо сущности.

Файлы к заметке

Мой Doxyfile.

Проект с комментариями для Doxygen.

Пример готовой документации в формате HTML сгенерированной Doxygen.

Для создания документации перейдите в директорию docs и запустите doxygen.