用doxygen爲C/C++程序自動生成文檔（二）－doxygen風格註釋簡介

用doxygen爲C/C++程序自動生成文檔（二）－doxygen風格註釋簡介

2009-9-29 21:41:05    收藏  |  打印  | 投票(16)  |  評論(0)  |  閱讀(80132)  ◇字體：［大 中 小］

doxygen爲C/C++程序自動生成文檔之文檔化代碼（doxygen風格註釋簡介）
      轉載請註明：嵌入式在線馮華的blog  
 

    如果打算使用doxygen爲代碼產生文檔，在編寫代碼時首先要爲代碼添加doxygen風格的註釋，這些doxygen風格的註釋可以稱爲文檔塊，添加註釋的這個動作可以稱爲文檔化代碼。Doxygen會根據相應的doxygen註釋塊爲代碼生成相應的文檔。

    對每個代碼條目，doxygen有兩種（在某些情況下可以3種）類型的說明，共同組成文檔：簡要說明和詳細說明，對應方法和函數可以有第三種風格的註釋，函數體內註釋。

    簡要說明只有一行長，詳細說明可以有多行。

 
註釋風格
詳細註釋可以有如下風格

1、JavaDoc風格的註釋，這種風格的註釋是在C風格的註釋塊開始處有兩個 “ * “，如下：

/**
 * ... 註釋塊 ...
 */

2、可以採用QT風格的註釋，這種風格的註釋是在C風格的註釋塊開始處“ * “後面緊跟”!”，如下：

/*!
 * ... 註釋塊 ...
 */

以上兩個例子中 text前的 “ * “ 是可選的，可以寫成

/**
 ... 註釋塊 ...
*/

和

/*!
... 註釋 ...
*/

3、單行註釋也可以採用如下方式

///
/// ... 註釋 ...
///

或

//!
//!... 註釋 ...
//!

4、如下注釋也是可以的

/********************************************//**
 *  ... 註釋
 ***********************************************/

或者

/////////////////////////////////////////////////
/// ...註釋...
/////////////////////////////////////////////////
簡要說明有如下格式

1、              使用\brief 命令指定簡要說明，簡要說明以”.” 結束，詳細說明在接下來的一個空行後開始，如下：

/*! \brief 簡要說明.
 *         簡要說明續.
 *
 *  詳細說明（上面要留一個空行）.
 */

如果配置文件中把 JAVADOC_AUTOBRIEF  設置成 YES，則可以使用JavaDoc風格註釋塊, 這種風格的註釋，簡要說明自動從“*“後開始 ，直到第一個”.”號結束，例如：

/** 簡要說明.
 *  詳細說明.
 */

多行C++風格註釋：

/// 簡要說明.
/// 詳細說明.

3、可以採用如下注釋：

/// 簡要說明.
/** 詳細說明. */

或者

//! 簡要說明. 

//! 詳細 （上面的空行是需要的）
//! 說明.

   上例中間空行用來分隔簡要說明和詳細說明的。請注意下面格式的註釋是不合法的，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);

};

 


如果配置文件中JAVADOC_AUTOBRIEF 設置成 YES，可以使用JavaDoc風格註釋
 

/**
 *  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);

};

 

未完待續， 下一篇 變量、宏、類型簡要註釋舉例，成員註釋舉例，函數註釋舉例