Документирование Doxygen. Введение

Оказывается, процесс написания документации может быть достаточно простым и понятным … при помощи Doxygen.

До недавнего времени у нас в проекте не было документации вообще. И вот мы взялись за s4g 0.9.1 версии, начали писать документацию в текстовых документах … это было так неинтересно и нудно.

По рекомендациям Евгения я глянул что такое Doxygen, посмотрел примеры, шибко они не впечатлили, но я решил попробовать, ибо у нас долгое время не было документации, а писать самому ее не очень хотелось. И я не пожалел, и теперь хочу написать об этом))

Doxygen — это кроссплатформенная программа для генерации документации из комментариев к исходному коду. Написана на C++. Лицензия GNU General Public License (можно использовать и не заморачиваться, если только использовать программу).

Ссылка на сайт перенаправляет сюда, на странице download ищите binary distribution (если нужна сама программа а не ее исходники) для Вашей ОС и качайте.

Поддерживает следующие языки: C, Objective-C, C#, PHP, Java, Python, IDL, Fortran, VHDL, Tcl, частично D.

Форматы вывода документации: HTML, LATEX, RTF (MS Word), Man pages, XML.

То есть можно настроить вывод в HTML, залить это все на сервер и получится … статический сайт с документацией!

Программа имеет англоязычный интерфейс (doxywizard), а также настройку в конфигурационном файле (для каждого проекта может быть свой файл настроек).

Статья Документирование с Doxygen. Основные настройки

Doxygen позволяет настраивать внешний вид, управлять навигацией, изменять структуру. Частично поддерживает HTML теги. Также может строить разного рода диаграммы и графы.

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

Казалось бы … какая может получится документация из комментариев? Вполне нормальная.

Примеры нашей документации к движку SkyXEngine и скриптовому языку s4g.

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

Если процесс документирования не откладывать на самый выпуск продукта, а вести его совместно с программированием (расставлять комментарии в стиле документирования), что не составляет особо труда, то документация будет сделана практически сама собой))

Мне удобно оформлять комментарии как перед кодом так и после, Doxygen это понимает, и мне всего лишь надо ему об этом сказать:

  • если комментарий перед кодом то он начинается так: //!
  • если комментарий после когда то он начинается так: //!<

Оставим детали настройки и оформления комментариев на следующую статью, а сейчас приведу примеру прокомментированного кода, из которого будет сгенерирована документация.

Документирование перечисления и его частей:

//! все типы данных которые могут быть использованы в скриптах
enum S4G_TYPE
{
	S4G_TYPE_NONE		= -1,	//!< тип отсутствует ... что-то не так
	S4G_TYPE_NULL		= 0,	//!< пустое значение
};

Создание именованной группы и комментирование дефайнов:

/*! \name Уровни сообщений
@{*/

//! уведомление
#define S4G_MSG_LEVEL_NOTICE	0	

//! предупреждение
#define S4G_MSG_LEVEL_WARNING	1	

//! ошибка
#define S4G_MSG_LEVEL_ERROR		2	

//!@}

Комментирование функции и создание к ней заметки вида note:

/*! тип си(++) функции
 \note если функция возвращает значение #S4G_ERROR значит произошла ошибка и машина остановит выполнение кода,
если #S4G_OK значит функция успешно отработала */
typedef int(*s4g_c_function) (s4g_Main* s4gm);

Комментирование функции и каждого аргумента:

//! стандартная отрисовка материала, используются стандартные шейдеры, нужно для теней, отражений и прочего
SX_LIB_API void SML_MtlRenderStd(
	MtlTypeModel type,			//!< тип материала из MtlTypeModel
	float4x4* world,			//!< мировая матрица трансформации, либо 0 и будет применена единичная матрица
	ID slot,					//!< текстурный слот в который установить текстуру
	ID id_mtl					//!< идентификатор материала из которого будет браться текстура
	);

Как видно из приведенных примеров документированного кода, документация это просто комментарии, которые немного оформлены.

В итоге при помощи простых правил комментирования и применения Doxygen проект обзаведется вполне нормальной документацией, а код проекта будет иметь комментарии))

Поделиться:

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *

*

*

code