doxygen教程之注释风格

Posted clever101

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了doxygen教程之注释风格相关的知识,希望对你有一定的参考价值。

作者:朱金灿
来源:clever101的专栏

为什么大多数人学不会人工智能编程?>>>

  doxygen是一个开源的C++接口文档生成工具。要使用doxygen生成接口文档,就必须遵循它的注释规范,下面对它的注释规范进行简单介绍。
1.JavaDoc风格注释:

/**
* your comment text.
*/

2.Qt风格:

/*!
* your comment text.
*/

3.仿c++风格:

///                               //!
/// your comment text.      或者: //! your comment text.
///                               //!

要使用哪种型态完全看自己的喜好。
  此外,由于Doxygen 对于批注是视为在解释后面的程序代码。也就是说,任何一个批注都是在说明其后的程序代码。如果要批注前面的程式码则需用下面格式的批注符号。

/*!< … 批注 … *//**< … 批注 … *///!< … 批注 …///< … 批注 …

  上面这个方式并不适用于任何地方,只能用在class 的member或是function的参数上。
一、文件注释,放于文件的开头:

/**
* @file           filename
* @brief        This is a brief description.
* @details     This is the detail description.
* @author    author
* @date        date
* @version    A001
* @par Copyright (c): 
*         XXX公司
* @par History:         
*    version: author, date, desc

*/

二、class的注释:

namespace MySPace
   
class MyClass
         
 public:           
 int member1 ;          
 int member2:           
 void member_function();   
 ;

加上批注后,就变成这样:

namespac MySPace
/**     @class 
* @brief 我的测试类
   *
   *   用来处理什么的逻辑
   *  @author ycj
   *  @version 0.1
   *  @date    13.09.02 
   */
class MyClass
   
public:          
int member1;     ///< 第一个member说明 …           
int member2;    ///< 第二个member说明 …          
int member_function(int a, int b);   ;


using namespace MySPace;
/**    
* @brief 自定义类别的member_funtion说明…
* @param[in] int a 参数a的说明    
* @param[out] int b 参数b的说明  
* @return 传回a+b
*/ 
int MyClass::member_function( int a, int b )   
      
return a+b ;   

三、数据结构注释,放于数据结构定义前:

/**
* The brief description.
* The detail description.
*/
typedef struct

   int var1;///<Description of the member variable
XXXX;

四、宏定义注释,放于宏定义上方或者右侧:

/** Description of the macro */
#define XXXX_XXX_XX        0

或者:

#define XXXX_XXX_XX  0 ///< Description of the macro. 

五、全局和静态变量注释:

/**  Description of global variable  */
int g_xxx = 0;
static int s_xxx = 0;///<  Description of static variable 

六、枚举类型注释:

/// 界面语言版本
enum UILanguageType

    LANGUAGE_ENGLISH, ///< 英文
    LANGUAGE_CHINESE  ///< 中文
;

以上例子仅供参考。

以上是关于doxygen教程之注释风格的主要内容,如果未能解决你的问题,请参考以下文章

Doxygen和JavaDoc注释风格(函数头部描述)(没看出有啥区别)

用doxygen风格注释代码生成文档

doxygen的使用给代码添加javadoc风格的注释

在QtCreator中使用doxygen

Xcode4快速Doxygen文档注释 — 简明图文教程

代码注释规范之Doxygen