web-dev-qa-db-ja.com

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をDoxygenNamespacesタブの下に、間接的にModulesタブの下に表示したいと思います。 名前空間ページの項目をクリックすると、Records::Interfaceを含むページが生成されます。 モジュールタブの項目をクリックすると、Records::Interfaceを含むページも生成されます。

私のDoxygenドキュメントでは、モジュールにある名前空間タブから欠落しているアイテムがあり、その逆もあります。このジレンマから。

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

c++namespacesdoxygendocumentation-generationdoxygen-addtogroup
26
Thomas Matthews

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の結果：

（メインバーにある）[モジュール]ボタンをクリックします。
ウィンドウの[レコード]モジュールをクリックします。

Records & Namespaces screen snapshot

例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の結果：

（メインバーにある）[モジュール]ボタンをクリックします。
ウィンドウの[レコード]モジュールをクリックします。

Records & Namespaces screen snapshot within namespace

概要

Doxygen \addtogroupコマンドの場所は、それがnamespace定義内にあるか外部にあるかによって、結果が異なります。名前空間の外部で宣言すると、上記の例1に示すように、DoxygenModulesタブに名前空間が表示されます。 \addtogroupコマンドが名前空間内に配置されている場合、上記の例2に示すように、DoxygenModulesタブには名前空間が表示されません。 名前空間をDoxygenModulesタブにリストする場合は、名前空間の外にある\addtogroupコマンドを見つけます。

31
Thomas Matthews

別の方法として、名前空間のドキュメントで \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 */
3
John