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

Question

У меня проблемы с распознаванием пространств имен и модулей 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 появиться на вкладке Пространства имен Doxygen и косвенно на вкладке Modules. Если щелкнуть элемент на странице пространств имен, откроется страница, содержащая Records::Interface, Нажатие на элемент на вкладке Модули также должно создать страницу, содержащую Records::Interface,

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

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

Answer 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*/

Doxygen Results:

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

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

//! Generic record interfaces and implementations
namespace Fields
{
/*!
 *  \addtogroup Fields
 *  @{
 */


  //! Describes the record interface  
  class Interface;

/*! @} End of Doxygen Groups*/

} // End namespace Fields

Doxygen Results:

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

Резюме

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

Answer 2

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

/**
 * \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 */