doxygenНачало работы с doxygen


замечания

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

Следует также упомянуть любые крупные темы в doxygen и ссылки на связанные темы. Поскольку документация для doxygen нова, вам может потребоваться создать начальные версии этих связанных тем.

Комментирование вашего кода

Существует несколько способов отметить блок комментариев как подробное описание, чтобы этот блок комментариев был проанализирован Doxygen и добавлен в описание следующего элемента кода в документации. Первый и наиболее распространенный - комментарии стиля C с дополнительной звездочкой в ​​последовательности запуска комментария, например:

/**
 * … text …
 */
int dummy_var;
 

Следующая альтернатива - использовать стиль Qt и добавить восклицательный знак (!) После открытия последовательности блока комментариев в стиле C:

/*!
 * … text …
 */
void foo(void);
 

Третьей альтернативой является использование блока по меньшей мере двух строк комментария C ++, где каждая строка начинается с дополнительной косой черты или восклицательного знака:

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

или же

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

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

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

Обратите внимание на 2 слэша, чтобы закончить нормальный блок комментариев и запустить специальный блок комментариев.

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

Для структурирования и форматирования созданной документации Doxygen предоставляет большое количество (> 170) специальных команд. Все команды в документации начинаются с обратного слэша () или знака at (@).

Например

/**
 * \brief    A brief description in one short sentence.
 */
 

эквивалентно

/**
 * @brief    A brief description in one short sentence.
 */
 

Для краткого описания есть также несколько возможностей:

Можно использовать команду \brief с одним из указанных блоков комментариев. Эта команда заканчивается в конце абзаца, поэтому подробное описание следует за пустой строкой.

/** \brief Brief description. 
 * Brief description continued. 
 * 
 * Detailed description starts here. 
 */ 
 

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

/// Brief description which ends at this dot. Details follow 
/// here. 
 

И, наконец, здесь приведен пример полной документации функции с doxygen:

/**
 * \brief   The function bar. 
 *
 * \details This function does something which is doing nothing. So this text
 *          is totally senseless and you really do not need to read this,
 *          because this text is basically saying nothing.
 *
 * \note    This text shall only show you, how such a \"note\" section
 *          is looking. There is nothing which really needs your notice,
 *          so you do not really need to read this section.
 *
 * \param[in]     a    Description of parameter a.
 * \param[out]    b    Description of the parameter b.
 * \param[in,out] c    Description of the parameter c.
 *
 * \return        The error return code of the function.
 *
 * \retval        ERR_SUCCESS    The function is successfully executed
 * \retval        ERR_FAILURE    An error occurred
 */

errcode_t bar(int a, int b, int c)
{    
    /** More detailed description inside the code */
}
 

источник и дополнительная информация на домашней странице Doxygen

Установка или настройка

Подробные инструкции по настройке или установке doxygen.