Документирование пространств имен с 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: документирование пространств имен

Ответ 1

Я провел эксперимент с использованием 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 за пределами пространства имен.

Ответ 2

В качестве альтернативы вы также можете использовать \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 */