Doxygen的特殊命令字

Doxygen在進行註釋的時候，有很多以@或者\開頭後面加上一個特殊命令的欄位，然後就可以在生成文件的時候有特殊的作用，我一般喜歡用@，所以後面的命令都使用這個標籤，下面我來介紹一下。

結構類的表達

• @addtogroup [(title)]

使用@defgroup同樣可以定義一個組，但是相比之下，多次使用相同<name>的@addtogroup命令並不會出現警告，而它是一個將命令中附帶的title與文件進行合併的組。
title是可選的，所以該命令可以使用@{和@}新增一定數量的實體到一個已存在的組裡。例如：

/*! \addtogroup mygrp
   *  Additional documentation for
 
 group 'mygrp'
   *  @{
   */

  /*!
   *  A function
   */
  void func1()
  {
  }

  /*! Another function */
  void func2()
  {
  }

  /*! @} */

• @callgraph

當該命令放置到一個函式或方法的註釋塊中，且HAVE_DOT設為YES，doxygen將建立一個呼叫圖。

• @callergraph

當該命令放置到一個函式或方法的註釋塊中，且HAVE_DOT設為YES，doxygen將建立一個呼叫者圖。

• @hidecallgraph

當該命令放置到一個函式或方法的註釋塊中，且HAVE_DOT

設為YES，doxygen將不建立一個呼叫圖。

• @hidecallergraph

當該命令放置到一個函式或方法的註釋塊中，且HAVE_DOT設為YES，doxygen將不建立一個呼叫者圖。

• @category [] []

只適用於Object-C：為一個名為<name>的類指定一個文件註釋塊，此命令引數應與@class相同

• @class [] []

為一個名字為<name>類指定一個文件註釋塊，可選擇指定的一個頭檔案和一個頭名稱。如果指定了一個頭檔案，在HTML文件中將包含一個指向次標頭檔案的完全副本的連結。<header-name>

引數可用於覆蓋<header-file>之外的類文件中所使用連結名稱，如果在預設包含路徑中無法定位包含檔案(如

/* A dummy class */
class Test
{
};
/*! \class Test class.h "inc/class.h" 
 *  \brief This is a test class. 
 * 
 * Some details about the Test class. 
 */

• @def

用於定義一個#define的註釋，例如：

/*! \file define.h    
    \brief testing defines

    This is to test the documentation of defines.
*/
/*! \def MAX(x,y) 
    Computes the maximum of \a x and \a y.
*/
/*!    
    Computes the absolute value of its argument \a x.
*/
#define ABS(x) (((x)>0)?(x):-(x))
#define MAX(x,y) ((x)>(y)?(x):(y))
#define MIN(x,y) ((x)>(y)?(y):(x))         
    /*!< Computes the minimum of \a x and \a y. */

• @defgroup (group title)

為類、檔案或名稱空間的組，指定一個文件註釋塊，可以用於類、檔案、名稱空間和文件的其他類別進行歸類，也可以將組作為其他組的成員，這樣就可以建立一個組的層次。

• @dir []

為一個目錄指定一個文件註釋塊，path fragment引數應包含一個路徑名和一個與專案中其他路徑不一樣的唯一一個全路徑(The “path fragment” argument should include the directory name and enough of the path to be unique with respect to the other directories in the project.)

• enum

為一個名字為<name>的列舉型別指定一個文件註釋塊，如果此列舉是類中的一個成員，且文件塊處於類定義之外，類的作用於同樣需要指定。如果一個註釋塊位於列舉宣告之前，那麼@enum註釋可能被省略。
注意：一個無名的列舉型別將不能被文件化，但一個無名的列舉值是可以使用的。
例如：

class Enum_Test
{  
public:    
    enum TEnum { Val1, Val2 };    
    /*! Another enum, with inline docs */    
    enum AnotherEnum     
    {       
        V1, /*!< value 1 */      
        V2  /*!< value 2 */    
    };
};

/*! \class Enum_Test 
 * The class description. 
 */
/*! @enum Enum_Test::TEnum 
 * A description of the enum type. 
 */
/*! @var Enum_Test::TEnum Enum_Test::Val1 
 * The description of the first enum value. 
*/

• @example

為一個原始碼的例子指定一個文件註釋塊，<file-name>是原始碼檔名，在註釋塊包含的文件之後，將包含此檔案的文字。所有的例子將被放入一個列表中，為了已文件化的成員和類，與文件之間的交叉引用，將對原始碼進行掃描，原始檔或目錄將在doxygen的配置檔案中使用EXAMPLE_PATH標記指定。

如果<file-name>也就是在EXAMPLE_PATH標記指定的例子檔名，並非是唯一的，你需要包含它的絕對路徑，以消除它的二義性。

如果例子中需要多個原始檔，可以使用@include命令，例如：

/** A Example_Test class. 
 *  More details about this class. 
 */
class Example_Test
{
public:    
/** An example member function.     
 *  More details about this function.    
 */    
 void example();
};
void Example_Test::example() {}
/** @example example_test.cpp 
 * This is an example of how to use the Example_Test class. 
 * More details about this example. 
 */

下面是例子檔案example_test.cpp

void main()
{ 
    Example_Test t; 
    t.example();
}

• @endinternal

這個命令結束一個以@internal開頭的文件塊。只要當INTERNAL_DOCS設定為YES時在@internal和@endinternal之間的文件才可見。

• @extends

當程式語言不支援這個特性時，比如C語言，就用這個命令手動指定一個繼承關係，。

在例子目錄中manual.c檔案將顯示如何使用這個命令。

• @file []

為一個名字為<name>的原始檔或者標頭檔案，指定一個文件註釋塊。如果檔名本身並不是唯一的，那麼這個檔名可能包含(部分包含)了它的路徑，如果該檔名被省略(如@file後留空)，那麼包含@file命令的文件塊將屬於它已定位到的那個檔案。

要點：全域性函式，變數，型別轉換，列舉的文件只能包含在輸出中，並且他們也已被文件化。

例子：

/** @file file.h 
 * A brief file description. 
 * A more elaborated file description. 
 */
/** 
 * A global integer value. 
 * More details about this value. 
 */
extern int globalValue;

注意：上面的例子中JAVADOC_AUTOBRIEF已經設定為YES

• @fn (function declaration)

為一個函式(全域性函式或者類的成員函式)指定一個文件註釋塊，此命令只有在一個註釋塊沒有放到函式宣告前面或者後面時才需要。

如果註釋塊放到了函式宣告的前面或者後面，此命令可省略(為了避免重複)。

警告：在此命名並非絕對需要時不要使用，否則將導致資訊重複的錯誤。

class Fn_Test
{ 
public: 
    const char *member(char,int) throw(std::out_of_range);
};
const char *Fn_Test::member(char c,int n) throw(std::out_of_range) {}
/*! @class Fn_Test 
 * @brief Fn_Test class. 
 * 
 * Details about Fn_Test. 
 */
/*! @fn const char *Fn_Test::member(char c,int n)  
 *  @brief A member function.
 *  @param c a character.
 *  @param n an integer. 
 *  @exception std::out_of_range parameter is out of range. 
 *  @return a character pointer. 
 */

• @headerfile []

用於類，結構，聯合的文件，同時這些文件都位於它們定義的前面。此命令的引數與@cmdclass命令的第二、三個引數相同。header-file名稱會引用一個檔案，它能被應用程式為獲取類，結構，聯合的定義而包含。<header-name>引數可用於覆蓋<header-file>之外的類文件中所使用連結名稱，如果在預設包含路徑中無法定位包含檔案(如

@headerfile test.h "test.h"
@headerfile test.h ""
@headerfile "" 

使用尖括號時你無需指定目標，如果你希望明確地指出，也可以使用一下方式：

@headerfile test.h <test.h>
@headerfile test.h <>
@headerfile <> 

• @hideinitializer

一個定義的預設值和一個變數的初始化都將顯示在文件中，除非它們的行數超過30。放置該命令在一個定義或者變數的註釋塊中，初始化將一直被隱藏。

• @idlexcept

表明了該註釋塊包含的文件是為了一個名字為<name>的IDL異常

• @implements

用於手動指定一個繼承關係，當程式語言不支援這個特性時(如C語言)。

• @ingroup ( [ ])

若該命令被放置到一個類，檔案，名稱空間的註釋塊中，它將新增一個<groupname>的組或者是組id。

• @interface [] []

為一個名字為<name>的介面指定一個文件註釋塊，引數與@class命令相同

• @internal

該命令開始一個僅僅為了內部使用的文件段，這個段落在註釋塊結尾處結束。你也可以通過使用命令@endinternal提前結束該內部文件段。

如果該命令被放置的一個小節中(見@section中的例子)，那麼命令後的所有子小節將被看成internal，只有與其在同一層級的新節才能重新可見。

• @mainpage [(title)]

如果該命令被放置到一個註釋塊，此塊將被用於定製HTML的索引頁，或latex的首章。這個很常用，就是生成段落的開始頁面的內容，我一開始研究了好久才在stackoverflow上面查到應該這樣用！！

title引數是可選的，並能替換掉doxygen生成的預設標題。如果你不需要任何標題，可以在命令後指定notitle。
例如：

/*! \mainpage My Personal Index Page
 *
 * \section intro_sec Introduction
 *
 * This is the introduction.
 *
 * \section install_sec Installation
 *
 * \subsection step1 Step 1: Opening the box
 *
 * etc...
 */

• @memberof

該命令使得類中的一個成員函式與@relates有相同的功能。 只有用這個命令函式才能被表述為一個類的真正成員。當程式語言不支援成員函式的概念時它將非常有用(如C語言)。

• @name [(header)]

該命令將成員組中的頭定義轉變成一個註釋塊，註釋塊將位於一個包含成員組的//@{ ... //@} 塊。

• @namespace

為一個名字為<name>的名稱空間指定一個文件註釋塊

• @nosubgrouping

可放置在一個類文件中，用於在合併成員組時，避免doxygen放置一個公有，保護或者私有的子分組。

• @overload [(function declaration)]

用於為一個過載成員函式生成後續的標準文字：這是一個未來便利而提供的過載函式，它不同於上述函式，只包含那些它接受的引數。

如果在函式宣告或者定義之前，無法定位過載成員函式的文件，能用可選引數來指定正確的函式。在生成的訊息之後將會附帶文件塊內其他的文件。

注意：你要承擔起確認文件的過載成員正確與否的責任，在這種情況下為了防止文件重新排列，必須將SORT_MEMBER_DOCS設定為NO。

注意：在一行註釋中@overload命令無法工作

例如：

class Overload_Test 
{
public: 
    void drawRect(int,int,int,int); 
    void drawRect(const Rect &r);
};
void Overload_Test::drawRect(int x,int y,int w,int h) {}
void Overload_Test::drawRect(const Rect &r) {}
/*! @class Overload_Test 
 *  @brief A short description. 
 *
 *  More text. 
 */
/*! @fn void Overload_Test::drawRect(int x,int y,int w,int h) 
 * This command draws a rectangle with a left upper corner at ( \a x , \a y ), 
 * width \a w and height \a h.  
 */
/*!
 * @overload void Overload_Test::drawRect(const Rect &r) 
 */

• @package

為一個名字為<name>的Java包指定一個文件註釋塊。

• @page (title)

指定一個註釋塊，它包含了一個與特定的類，檔案，成員非直接關聯的文件塊。HTML生成器將建立一個包含此文件的頁面，而latex生成器將在’頁文件’的章節中開始一個新的小節。

例如：

/*! @page page1 A documentation page  
    @tableofcontents  Leading text.  
    @section sec An example section  This page contains the subsections @ref subsection1 and @ref subsection2.  
    For more info see page @ref page2.  
    @subsection subsection1 The first subsection  Text.  
    @subsection subsection2 The second subsection  
    More text.
 */
/*! @page page2 Another page  
    Even more info.
*/

• @private

指定註釋塊中的私有文件化成員，它只能被同一類的其他成員訪問。

注意：doxygen會自動確認面對物件語言中的成員保護層級，此命令用於不支援保護層級的概念的語言。(如C語言和PHP4)

私有成員小節的開始處，有一種與C++中private:類似的標記法，使用@privatesection

• @privatesection

開始一個私有成員的小節，與C++中private類似的標記法，指定註釋塊中的私有文件化成員，它只能被同一類的其他成員訪問。

• @property (qualified property name)

為一個屬性(即可是全域性也可是一個類成員)指定一個文件註釋塊，此命令等價於@var @fn

• @protected

指定註釋文件中的保護文件化成員，它只能被同一類的其他成員或派生類訪問。

注意：doxygen會自動確認面對物件語言中的成員保護層級，此命令用於不支援保護層級的概念的語言。(如C語言和PHP4)

保護成員開始處，有一種與C++中protected:類似的標記法，使用@privatesection

• @protocol [] []

為Object-C中名字為<name>的協議指定一個文件註釋塊，它的引數與@class相同。

• @public

指定註釋文件中的公有文件化成員，它只能其他類或函式訪問。

注意：doxygen會自動確認面對物件語言中的公有層級，此命令用於不支援公有層級的概念的語言。(如C語言和PHP4)

公有成員開始處，有一種與C++中public:類似的標記法，使用@publicsection

• @pure

指定註釋文件中純虛成員，它是抽象的沒有被實施的成員。

注意：此命令用於不支純虛方法的概念的語言。(如C語言和PHP4)

• @relates

用於名字為<name>非成員函式的文件，它可以放置在這個函式到類文件的“關聯函式”小節內，該命令對於非友元函式與類之間建立強耦合是非常有用的。它無法用於檔案，只能用於函式。

/*!  
 * A String class. 
 */
class String
{ 
    friend int strcmp(const String &,const String &);
};
/*! 
 * Compares two strings. 
 */
int strcmp(const String &s1,const String &s2)
{
}
/*! @relates String 
 * A string debug function. 
 */
void stringDebug() 
{
}

• @related

同@relates

• @relatesalso

用於名字為<name>非成員函式的文件，它可以放置在這個函式到類文件的“關聯函式”小節內，也可是遠離它正常文件的位置。該命令對於非友元函式與類之間建立強耦合是非常有用的。只能用於函式。

• @showinitializer

只顯示定義的預設值和變數的初始化，如果它們的文字行數小於30，在變數或定義的註釋塊中放置這個命令，初始化過程將無條件被顯示出來。

• @static

指定註釋文件中靜態成員，它定義在類中，但不屬於類的例項化，它屬於整個類！

注意：此命令用於不支靜態方法的概念的語言。(如C語言和PHP4)

• @struct [] []

為一個名字為<name>的結構體指定一個文件註釋塊，它與引數@class相同

• @typedef (typedef declaration)

為一個型別轉換指定一個文件註釋塊，它與引數@var @fn相同

• @union [] []

為一個名字為<name>的聯合體指定一個文件註釋塊，它與引數@class相同

• @var (variable declaration)

為一個變數或者列舉值指定一個文件註釋塊，它與引數@typedef @fn相同

• @vhdlflow [(title for the flow chart)]

這是一個硬體描述語言特定的命令，可以放在文件中產生一個邏輯過程的流程圖。流程圖的標題可以隨意指定。

• @weakgroup [(title)]

用法與@addtogroup相似，但當解決組定義衝突時，它將會有一個更低的優先順序。