勤能补拙,Expter

成都游戏Coder,记录游戏开发过程的笔记和心得!

转:doxygen 使用简介(C,C++为代码作注释)

 如果打算使用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);

};


From:http://www.embstudy.org/home/space.php?uid=8&do=blog&id=66

posted on 2009-07-25 17:46 expter 阅读(676) 评论(1)  编辑 收藏 引用

评论

# re: 转:doxygen 使用简介(C,C++为代码作注释) 2009-07-25 18:21 黑色灵猫

本文不错,最近刚弄好lua的,返回来看下c++的doxygen,免得再google了  回复  更多评论   


只有注册用户登录后才能发表评论。
网站导航: 博客园   IT新闻   BlogJava   知识库   博问   管理