c++ - 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 Namespacesタブの下に表示し、間接的にModulesタブの下に表示したいと思います。Namespacesページのアイテムをクリックすると、を含むページが生成されますRecords::Interface。[モジュール] タブのアイテムをクリックすると、を含むページも生成されますRecords::Interface。

私の Doxygen のドキュメントでは、このジレンマに起因する不一致のために、 モジュールにある名前空間タブに欠落している項目があり、その逆も同様です。

では、例 1 と例 2 のどちらが適切な方法でしょうか。{Doxygen マニュアルは、このトピックについて明確ではありません。}
Doxygen: \addtogroup
Doxygen: 名前空間の文書化

Answer 1

Doxygen と 2 つの例を使用して実験を行いました。結果は次のとおりです。例のクラス名は、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の結果:

Modules ボタンをクリックします (メインバーにあります)。
ウィンドウ内の「レコード」モジュールをクリックします。

例 2: Namespace 内 (クラス名を Fields に変更)

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


  //! Describes the record interface  
  class Interface;

/*! @} End of Doxygen Groups*/

} // End namespace Fields

Doxygenの結果:

Modules ボタンをクリックします (メインバーにあります)。
ウィンドウ内の「レコード」モジュールをクリックします。

概要

Doxygen コマンドの場所は、定義\addtogroup内にあるか外部にあるかによって結果が異なります。名前空間の外で宣言すると、上記の例 1 に示すようにnamespace、Doxygenモジュールタブに名前空間が表示されます。コマンドが名前空間内に配置されている場合、上記の例 2 に示すように\addtogroup、Doxygenモジュールタブには名前空間が表示されません。 名前空間を [ Doxygenモジュール] タブに表示する場合\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 */