织梦CMS - 轻松建站从此开始!

罗索实验室

当前位置: 主页 > 基础技术 > UML,RUP,SCM >

doxygen为C/C++程序自动生成文档之文档化代码

落鹤生 发布于 2012-09-20 09:16 点击:次 
如果打算使用doxygen为代码产生文档,在编写代码时首先要为代码添加doxygen风格的注释,这些doxygen风格的注释可以称为文档块,添加注释的这个动作可以称为文档化代码。Doxygen会根据相应的doxygen注释块为代码生成相应的文档。
TAG:

如果打算使用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++代码样例

  1. //!  A test class. 
  2. /*! 
  3.   A more elaborate class description. 
  4. */ 
  5.  
  6. class Test 
  7.   public:  
  8.     //! An enum. 
  9.     /*! More detailed enum description. */ 
  10.     enum TEnum { 
  11.         TVal1, /*!< Enum value TVal1. */  
  12.         TVal2, /*!< Enum value TVal2. */  
  13.         TVal3  /*!< Enum value TVal3. */  
  14.     } 
  15.     //! Enum pointer. 
  16.     /*! Details. */ 
  17.     *enumPtr,//! Enum variable. 
  18.              /*! Details. */ 
  19.  
  20.     enumVar; //! A constructor. 
  21.              
  22.     /*! 
  23.       A more elaborate description of the constructor. 
  24.     */ 
  25.     Test(); 
  26.  
  27.     //! A destructor. 
  28.     /*! 
  29.       A more elaborate description of the destructor. 
  30.     */ 
  31.    ~Test(); 
  32.  
  33.     //! A normal member taking two arguments and returning an integer value. 
  34.     /*! 
  35.       /param a an integer argument. 
  36.       /param s a constant character pointer. 
  37.       /return The test results 
  38.       /sa Test(), ~Test(), testMeToo() and publicVar() 
  39.     */ 
  40.  
  41.     int testMe(int a,const char *s); 
  42.  
  43.     //! A pure virtual member. 
  44.     /*! 
  45.       /sa testMe() 
  46.       /param c1 the first argument. 
  47.       /param c2 the second argument. 
  48.     */ 
  49.     virtual void testMeToo(char c1,char c2) = 0; 
  50.  
  51.     //! A public variable. 
  52.     /*! 
  53.       Details. 
  54.     */ 
  55.     int publicVar; 
  56.  
  57.     //! A function variable. 
  58.     /*! 
  59.       Details. 
  60.     */ 
  61.     int (*handler)(int a,int b); 
  62. }; 

如果配置文件中JAVADOC_AUTOBRIEF 设置成 YES,可以使用JavaDoc风格注释

  1. /** 
  2.  *  A test class. A more elaborate class description. 
  3.  */ 
  4. class Test 
  5.   public
  6.     /** 
  7.      * An enum. 
  8.      * More detailed enum description. 
  9.      */ 
  10.     enum TEnum { 
  11.           TVal1, /**< enum value TVal1. */  
  12.           TVal2, /**< enum value TVal2. */  
  13.           TVal3  /**< enum value TVal3. */  
  14.          } 
  15.        *enumPtr, /**< enum pointer. Details. */ 
  16.        enumVar;  /**< enum variable. Details. */ 
  17.        
  18.       /** 
  19.        * A constructor. 
  20.        * A more elaborate description of the constructor. 
  21.        */ 
  22.       Test(); 
  23.  
  24.       /** 
  25.        * A destructor. 
  26.        * A more elaborate description of the destructor. 
  27.        */ 
  28.      ~Test(); 
  29.  
  30.       /** 
  31.        * a normal member taking two arguments and returning an integer value. 
  32.        * @param a an integer argument. 
  33.        * @param s a constant character pointer. 
  34.        * @see Test() 
  35.        * @see ~Test() 
  36.        * @see testMeToo() 
  37.        * @see publicVar() 
  38.        * @return The test results 
  39.        */ 
  40.        int testMe(int a,const char *s); 
  41.  
  42.       /** 
  43.        * A pure virtual member. 
  44.        * @see testMe() 
  45.        * @param c1 the first argument. 
  46.        * @param c2 the second argument. 
  47.        */ 
  48.        virtual void testMeToo(char c1,char c2) = 0; 
  49.  
  50.       /** 
  51.        * a public variable. 
  52.        * Details. 
  53.        */ 
  54.        int publicVar; 
  55.  
  56.       /** 
  57.        * a function variable. 
  58.        * Details. 
  59.        */ 
  60.        int (*handler)(int a,int b); 
  61. }; 

 

(秩名)
本站文章除注明转载外,均为本站原创或编译欢迎任何形式的转载,但请务必注明出处,尊重他人劳动,同学习共成长。转载请注明:文章转载自:罗索实验室 [http://www1.rosoo.net/a/201209/16277.html]
本文出处:嵌入式学习网 作者:秩名
顶一下
(0)
0%
踩一下
(0)
0%
------分隔线----------------------------
发表评论
请自觉遵守互联网相关的政策法规,严禁发布色情、暴力、反动的言论。
评价:
表情:
用户名: 验证码:点击我更换图片
栏目列表
将本文分享到微信
织梦二维码生成器
推荐内容