【工具】Doxygen代码注释规范_doxygen注释规范

代码注释规范

一、特殊文档块

对于任何一行代码来说，会有两种(也可能是三种)注释方式，并且会一同放置到文档中，-种是简明描述，另一种是细节描述，这两种方式都是可选的。而方法和函数也可能使用第三种描述的方式，它被称为\“inbody\”描述，并包含方法和函数内所有注释块之间的联系。

多于一个的简明或者细节描述是能被接受的(不推荐，将会无法判定描述的顺序)。

建议简明描述使用一.个短小的单行方式，而细节描述要提供足够的长度以包容更多的细节文档。一个\ "inbody“ \ 描述可看成一个细节描述，或者是执行细节的集合。以HTML方式输出的简明描述可在文档行引用之处支持冒泡提示For the HTML output brief descriptions are also use to provide tooltips at places where an item is
referenced

C注释风格

/**
*  ...text...
* /
1
2
3

C++ 注释风格

///
///  ...text...
///
1
2
3

//!
//!  ...text...
//!
1
2
3

我们平时使用较多的

/******************************************
*  ...text...
******************************************/
1
2
3

/
///  ...text...
/
1
2
3

2.如果在配置文件中将JAVADOC_ AUTOBRIEF 设置为YES，可使用JavaDoc 注释块，并自动展开一个简明描述。

在出现第一个“.”处结束，后跟一个空格或空白行。这里有一一个例子：

/** Brief description which ends at this dot. Details follow
* here.
*/
1
2
3

（C++的多行注释一样有效 /// ）

例程（JAVADOC注释风格）：

#include <stdio.h>

/**
* A test class. A more elaborate class descript ion.
*/
class Test
{
public:
	/**
	* An enum.
	* More detailed enum descript ion.
	*/
	enum TEnum 
	{
		TVal1,/**< enum value TVal1. */
		TVal2,/**< enum value TVal2. */
		TVal3 /**< enum value TVal3. */
	}
		*enumPtr, /**< enum pointer. Details. */
		enumVar; /**< enum variable. Details. */
	

	/**
	* A construc tor.
	* A more elaborate description of the construc tor.
	*/
	Test();

	/**
	* A destructor.
	* A more elaborate description of the des tructor.
	*/
	~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 cl, char c2) = 0;

	/**
	* a public variable.
	* Details.
	*/
	int publicVar;

	/**
	* a function variable.
	* Details.
	*/
	int(*handler)(int a, int b);

};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

二、成员之后放置文档

如果你希望文档化一个文件，结构，联合，类以及枚举的成员，需要为复合体中的这些成员放置文档，有时希望放置在成员之后的文档块，可以替换掉原有的块，因此要在注释块中加入“<”标记。 请注意“<”作为一个函数参数值是有效的Note that this also works for the parameters of a function 。

example：
QT注释风格：

int var; /*!< Detailed description after the member */
1

JAVADOC ( C ）注释风格：

int var; /**< Detailed description after the member */
1

C++注释风格：

int var; ///< Detailed description after the member
1

int var; //!< Detailed description after the member
1

一般在结构体成员后放置一个简明描述

函数中可用 “@param” 来文档化它的参数，使用“[in]，[out]， [in, out]”文档化它的执行方向。
内联文档则可能从方向属性开始记录For inl ine documentation this is also possible by starting with the directionattribute，例如:

void foo(int v /**< [in] docs for input parameter v. */);
1

警告:
这些块只能用于文档化成员和参数，无法用于文件，类，联合，结构，组，名字空间以及枚举，此外下面结构化命令(比如\class)是不允许在这些注释块中出现的。

二、使用破折号

在每一行的开始处放置列对齐的多个减号“-”， 一个bullet列表将自动生成。使用“-” 紧跟“#”，也能生成一个带编号的列表。
这有一个例子:

/********************************************
* A test class. A more elaborate class descript ion.
* A list of events:
*	- mouse events
*		- # mouse move event
*		- # mouse click event\n
*			More info about the click event.
*		-# mouse double click event
*	- keyboard events
*		-# key down event
*		-# key up event
*
* More text here.
**********************************************/
1
2
3
4
5
6
7
8
9
10
11
12
13
14

如果在列表中使用tabs进行缩排，请确认配置文件中TAB. _SIZE选项是否设置了正确的tab尺寸。可在列表结束的缩排层级的空白处放置一-一个点“.”或者开始一个新的段落，即可结束一个列表。这有一个不言自明的例子:

使用HTML命令，可以是注释段落更清晰

三、组合

Doxygen一共有三种组合的机制，一种工作于全局级别，为每一个组创建一个新页面。
在文档中这些组被称为“模块”
第二种工作在一些复合体的成员列表中，参考“成员组”。
第三种工作于页面，参考“子页面”。

模块

成员组

如果一个复合体(比如一一个类或文件)有很多成员，通常希望能将成员们一-同合并到组中,

如果你喜欢C风格注释，用以下两种块模板来定义一个成员组，注意成员组内部的组成员都必须是确实存在。
规范：

//@{
...
//@}
1
2
3

或者

/*@{*/
...
/*@}*/
1
2
3

example：

//@{
/** Same documentation for both members. Details */
void funclInGroup1() ;
void func2InGroup1() ;
//@}
1
2
3
4
5

在一个块开始标记“@{”之前可以放置一个单独的注释块，而此块必须包含@name (或\name)命令， 用于指定组的头部，也可选择让注释块包含更多的组信息。

成员组的嵌套是不被允许的。

如果一个类的成员组中的全部组成员都有相同的类型和保护级别(比如全是静态公有成员)，那么整个成员组被当成类型/保护级别组的一-个 子分组(例如成员组将被看\“静态公有成员\”节点的子节点)，假如两个或多个成员有不同的类型，那么组会将它们置于相同的层级上自动生成–个组，假如你希望强制类的全部组成员在顶层，你需要在类文档中加入\nosubgrouping命令。

/** Test_sub class.
* Details 
*/
class Test_sub
{
public:

	/** Same documentation for both members. Details */
	void funclInGroup1() ;
	void func2InGroup1() ;
	/** Function without group. Details. */
	void ungroupedFunction();
	void func1InGroup2();
protected:
	void func2InGroup2();
};

/** @name Group1
* Description of group 1.
*/
//@{
void Test_sub::funclInGroup1() {}
void Test_sub::func2InGroup1() {}
//@}

/** @name Group2
* Description of group 2.
*/
//@{

/** Function 2 in group 2. Details. */
void Test_sub::func2InGroup2() {}

/** Function 1 in group 2. Details. */
void Test_sub::func1InGroup2() {}

//@}

/** \file
docs for this file
*/
//@{
//! one description for all members of this group
//! (because DISTRIBUTE _GROUP_ _DOC is YES in the config file)
#define A 1
#define B 2
void g_lob_func();
//@}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

执行效果

子页面

在“模块”章节中简述添加结构的替代方法，为了更自然和方便地增加额外结构到页面中，可以使用\subpage命令。

A页面用\subpage命令增加-一个链接到B页面，同时将B页面变成A页面的一个子页。这对于GA，GB两个组同样有影响，使得GB变为GA一部分的方法，将A页面置于GA组内，而将B页面置于GB组内即可。

//--------------------------- 主页的使用 （\page的说明可放在不同文件中）-------------------
//--------------------此处将页面添加到模块说明中
/** @defgroup groupA The Page Group A
* This is the first group
* @{
*/
/** @brief class CA in group A */
class CA {};

/** function in group A */
void funcA() {}

/** @} */// end of groupA

/*! \mainpage A simple manual
Some general info.

This manual is divided in the following sections:
- \subpage intro 
- \subpage advanced "Advanced usage"
*/

//-----------------------------------------------------------

/*! \page intro Introduction
* @ingroup groupA

This page introduces the user to the topic.
Now you can proceed to the \ref advanced "advanced section".
*/

//-----------------------------------------------------------

/*! \page advanced Advanced Usage
This page is for advanced users.
Make sure you have first read \ref intro "the introduction".
*/


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39