Документирование пространств имен с помощью 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 Пространства имен и косвенно на вкладке Модули . Если щелкнуть элемент на странице Пространства имен , откроется страница, содержащая 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 Результаты:

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

Пример 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 Результаты:

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

Основная информация

Расположение команды 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 */