Документирование пространств имен с Doxygen

У меня возникают проблемы с Doxygen, распознающим пространства имен и модули. Я считаю, что проблема связана с тем, размещать ли \addtogroup в пространстве имен или вне пространства имен.

Пример 1 за пределами пространства имен:

/*!
 * \addtogroup Records
 * @{
 */
//! Generic record interfaces and implementations
namespace Records
{
 //! Describes the record interface 
 class Interface;
} // End namespace Records
/*! @} End of Doxygen Groups*/

Пример 2 - в пространстве имен

//! Generic record interfaces and implementations
namespace Records
{
/*!
 * \addtogroup Records
 * @{
 */
 //! Describes the record interface 
 class Interface;
/*! @} End of Doxygen Groups*/
} // End namespace Records

Я хотел бы, чтобы namespace Records отображался на вкладке Damesgen Namespaces и косвенно на вкладке "Модули". Нажав на элемент на странице "Пространства имен", вы должны создать страницу, содержащую Records::Interface. Нажатие на элемент на вкладке "Модули" также должно содержать страницу, содержащую Records::Interface.

В документации Doxygen у меня есть элементы, отсутствующие на вкладке Пространства имен, которые находятся в модулях и наоборот, из-за моей несогласованности, вызванной этой дилеммой.

Итак, каков правильный метод, пример 1 или пример 2? {Руководство по Doxygen не ясно в этой теме.} Doxygen:\addtogroup Doxygen: документирование пространств имен

2 ответа

Я провел эксперимент с использованием Doxygen и двух примеров, и вот результаты. Названия классов в примерах были переименованы во избежание путаницы с Doxygen.

Пример 1, Вне пространства имен

/*!
 * \addtogroup Records
 * @{
 */
//! Generic record interfaces and implementations
namespace Records
{
 //! Describes the record interface 
 class Interface;
} // End namespace Records
/*! @} End of Doxygen Groups*/

Результаты доксигена:

Нажмите кнопку "Модули" (на главной панели). Нажмите кнопку "Записи" в окне.

Пример 2: В пространстве имен (класс переименован в поля)

//! Generic record interfaces and implementations
namespace Fields
{
/*!
 * \addtogroup Fields
 * @{
 */
 //! Describes the record interface 
 class Interface;
/*! @} End of Doxygen Groups*/
} // End namespace Fields

Результаты доксигена:

Нажмите кнопку "Модули" (на главной панели). Нажмите кнопку "Записи" в окне.

Резюме

Расположение команды Doxygen \addtogroup имеет разные результаты в зависимости от того, находится ли она в определении namespace или снаружи. Если объявлено вне пространства имен, вкладка Doxygen Modules отобразит пространство имен, как показано в примере 1 выше. Когда команда \addtogroup помещается внутри пространства имен, вкладка Doxygen Modules не отображает пространства имен, как показано в примере 2 выше. Если вы хотите, чтобы ваше пространство имен было указано на вкладке Doxygen Modules, найдите команду \addtogroup за пределами пространства имен.


В качестве альтернативы вы также можете использовать \ingroup Records в документации по пространству имен:

/**
 * \defgroup Records Title for records module
 * @brief Short doc of Records
 *
 * Long doc of Records.
 */
/**
 * @brief Generic record interfaces and implementations
 *
 * \ingroup Records
 */
namespace Records {
 /// Describes the record interface 
 class Interface;
} /* namespace Records */

licensed under cc by-sa 3.0 with attribution.