用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);

};

 

未完待续， 下一篇 变量、宏、类型简要注释举例，成员注释举例，函数注释举例