doxygen註釋塊

doxygen註釋塊其實就是在C"C++註釋塊的基礎新增一些額外標識, 使doxygen把它識別出來, 並將它組織到生成的文件中去。

在每個程式碼項中都可以有兩類描述, 這兩類描述將在文件中格式化在一起: 一種就是brief描述, 另一種就是detailed。 兩種都是可選的，但不能同時沒有。

顧名思義, 簡述(brief)就是在一行內簡述地描述。而詳細描述(detailed description)則提供更長, 更詳細的文件。

在doxygen中, 有多種方法將註釋塊標識成詳細描述:

1. 你可以使用JavaDoc風格, 即在C風格註釋塊開始使用兩個星號'*', 

就像這樣:

2. /**

3.  * ... 描述 ...

4.  */

5. 或者你使用Qt風格程式碼註釋, 即在C風格註釋塊開始處新增一個歎號'!':

6. /*!

7.  * ... 描述 ...

8.  */

註釋塊中間的星號是可選, 所以將註釋塊寫成:

/*!

 ... 描述 ...

*/

同樣也是有效的.

9. 第三種方法就是使用連續兩個以上C++註釋行所組成的註釋塊, 而每個註釋行開始處要多寫一個斜槓或寫一個歎號。像下行這樣:

10.///

11./// ... 描述 ...

12.///

或者

//!

//!... 描述 ...

//!

13. 一些人喜歡使他們的註釋塊在文件中顯得更為顯目

, 所以你也可以這麼做:

14./////////////////////////////////////////////////

15./// ... 描述 ...

16./////////////////////////////////////////////////

簡述同樣也可以同種寫法:

1. 一種是在一個doxygen註釋塊中使用這個命令只對當前一個文欄位有效, 所以詳細描述應該與之間隔一個空行.

像這樣:

/*! "brief 這裡是簡要描述.

 *         這裡仍然是簡要描述.

 *

 * 詳細描述從這裡開始.

 */

2. 如果在doxygen配置檔案將設定成YES。則JavaDoc風格將註釋塊中的第一個句子視為簡要描述, 這個句子可以以句號'.'、空格或者空行來結束:

3. /** 這裡是簡述, 並由句號結束. 詳細描述從這裡

4.  * 開始.

5. 
 
 */

這個功能同樣多行C++行註釋段中有效:

/// 這裡是簡述, 並由句號結束. 詳細描述從這裡

/// 開始..

6. 第三種方法就是詳細描述註釋段緊跟在一行C++註釋段後面, 至多隔一個空行, 如下面兩個例子:

7. /// 簡述.

8. /** 詳細描述. */

或者

//! 簡述.

//! 詳細描述

//! 從這裡開始.

注意最後一個例子, 例子那個空行是用來分隔簡述註釋段和詳細描述段的, 不能去掉.而且JAVADOC_AUTOBRIEF不應該被設定成YES.

看上去doxygen是相當富有彈性, 但下面的例子是非法的:

//! 這個簡述因為是多行的

//! 會被認為是詳細描述..

/*! 而這裡則是另外的詳細描述.

 */

因為doxygen只允許一個簡要和一個詳細描述。

此外, 如果在一個程式碼項的宣告之前有簡要描述而且在其定義之前也有簡要描述, 那麼doxygen只使用宣告之前的描述。而如果詳細描述出現了同樣的情況, doxygen則會使用定義之前的描述, 另外的描述會被忽略掉。

這裡有一個使用Qt風格的C++程式碼:

//! A test class. 

/*!

 A more elaborate class description.

*/

class Test

{

 public:

    //! An enum.

    /*! More detailed enum description. */

    enum TEnum { 

                 TVal1, /*!< Enum value TVal1. */ 

                 TVal2, /*!< Enum value TVal2. */ 

                 TVal3 /*!< Enum value TVal3. */ 

               } 

         //! Enum pointer.

         /*! Details. */

         *enumPtr, 

         //! Enum variable.

         /*! Details. */

         enumVar; 

    //! A constructor.

    /*!

      A more elaborate description of the constructor.

    */

    Test();

    //! A destructor.

    /*!

      A more elaborate description of the destructor.

    */

   ~Test();

    //! A normal member taking two arguments and returning an integer value.

    /*!

      "param a an integer argument.

      "param s a constant character pointer.

      "return The test results

      "sa Test(), ~Test(), testMeToo() and publicVar()

    */

    int testMe(int a,const char *s);

    //! A pure virtual member.

    /*!

      "sa testMe()

      "param c1 the first argument.

      "param c2 the second argument.

    */

    virtual void testMeToo(char c1,char c2) = 0;

    //! A public variable.

    /*!

      Details.

    */

    int publicVar;

    //! A function variable.

    /*!

      Details.

    */

    int (*handler)(int a,int b);

};

點選這裡檢視doxygen產生的HTML文件.

只有一行的註釋段包含的是簡述, 而多行的註釋段則包含的是詳細描述.

簡要描述可以被用來進行class、namespace或者檔案的成員描述, 被以較小的斜體字型顯示出來。(這種描述可以通過將設定成NO來隱藏。)預設情況下，簡要描述會被顯示成詳細描述的第一個句子。(這同樣可以通過將設定成NO來遮蔽。)在Qt風格中, 兩種描述都是可選的。

預設情況下, JavaDoc風格的註釋段和Qt風格的註釋段的行為是相同的。但這樣, 就不符合JavaDoc標準, 註釋段的第一個句應該自動識別為簡要描述。你應該設定， 來啟用這個功能。如果你設定了這個選項並想在句子中間放置一個句號, 你應該在後面新增一個反斜槓和一個空格. 就像下面的例子一樣:

 /** Brief description (e.g." using only a few words). Details follow. */

Here is the same piece of code as shown above, this time documented using the JavaDoc style and JAVADOC_AUTOBRIEF set to YES:

/**

 * A test class. A more elaborate class description.

 */

class Test

{

 public:

    /** 

     * An enum.

     * More detailed enum description.

     */

    enum TEnum { 

          TVal1, /**< enum value TVal1. */ 

          TVal2, /**< enum value TVal2. */ 

          TVal3 /**< enum value TVal3. */ 

         } 

       *enumPtr, /**< enum pointer. Details. */

       enumVar; /**< enum variable. Details. */

      /**

       * A constructor.

       * A more elaborate description of the constructor.

       */

      Test();

      /**

       * A destructor.

       * A more elaborate description of the destructor.

       */

     ~Test();

      /**

       * a normal member taking two arguments and returning an integer value.

       * @param a an integer argument.

       * @param s a constant character pointer.

       * @see Test()

       * @see ~Test()

       * @see testMeToo()

       * @see publicVar()

       * @return The test results

       */

       int testMe(int a,const char *s);

      /**

       * A pure virtual member.

       * @see testMe()

       * @param c1 the first argument.

       * @param c2 the second argument.

       */

       virtual void testMeToo(char c1,char c2) = 0;

      /** 

       * a public variable.

       * Details.

       */

       int publicVar;

      /**

       * a function variable.

       * Details.

       */

       int (*handler)(int a,int b);

};

點選這裡檢視doxygen產生的HTML文件.

不像其它的文件系統 , doxygen允許在程式碼項的定義之前面放置成員(包括全域性函式)的註釋。這種方法可以在原始檔中進行文件註釋工作。這就是使得標頭檔案可以比較簡潔, 使程式碼的實現人員更容易閱讀。比較折中的方案就是在宣告的地方新增簡要描述, 在實現的地方新增詳細描述。

在成員後面放置文件

如果你想對檔案、結構體、聯合體、類或者列舉的成員進行文件註釋的話, 並且要在成員中間添加註釋, 而這些註釋往往都是在每個成員後面。為此, 你可以使用在註釋段中使用'<'標識

Here are some examples:

int var; /*!< Detailed description after the member */

This block can be used to put a Qt style detailed documentation block after a member. Other ways to do the same are:

int var; /**< Detailed description after the member */

或者

int var; //!< Detailed description after the member

         //! 

或者

int var; ///< Detailed description after the member

         /// 

Most often one only wants to put a brief description after a member. This is done as follows:

int var; //!< Brief description after the member

或者

int var; ///< Brief description after the member

Note that these blocks have the same structure and meaning as the special comment blocks in the previous section only the < indicates that the member is located in front of the block instead of after the block.

Here is an example of the use of these comment blocks:

/*! A test class */

class Test

{

 public:

    /** An enum type. 

     * The documentation block cannot be put after the enum! 

     */

    enum EnumType

    {

      int EVal1,     /**< enum value 1 */

      int EVal2      /**< enum value 2 */

    };

    void member();   //!< a member function.

  protected:

    int value;       /*!< an integer value */

};

點選這裡檢視doxygen產生的HTML文件.

警告:

這種註釋方法只能在成員和引數中使用。它們不能用在描述檔案、類、聯合體、名字空間和列舉本身。此外, 在下一節提到的結構化命令(如"class)在這種註釋段中是無效的。

在其它地方進行註釋

雖然我們一般是在宣告和定義的前面新增文件註釋塊, 但也許出於某種情況需要將文件放在其它什麼位置上。比如我們需要編寫一段實際上不存在的檔案的描述。因此, Doxygen允許將文件放置在任何位置。(除了在函式體內或在一個普通的註釋段)

為了達到這種目的, 你唯一要做的就是在註釋段中使用結構化命令。

結構化命令(就像其它命令)由一個反斜槓("), 或 JavaDoc風格中使用的@來做開頭, 後面緊跟著命令名字和一些引數。例如, 你想註釋一個名為Test的類, 如下例:

/*! "class Test

    "brief A test class.

    A more detailed class description.

*/

命令"class被用來指示程式碼段中包含著關於Test類的文件.其它的結構化命令有:

·"struct 生成 C結構的文件.

·"union 生成聯合體的文件.

·"enum 生成列舉的文件.

·"fn 生成函式的文件.

·"var生成變數或typedef或列舉值的文件.

·"def 生成#define定義的文件.

·"file 生成關於一個檔案的文件.

·"namespace 生成名字空間的文件.

·"package 

相關推薦