【工具】Doxygen代码注释规范

最新推荐文章于 2024-07-14 23:07:52 发布

【初～心】

最新推荐文章于 2024-07-14 23:07:52 发布

阅读量1.7k

点赞数 2

分类专栏：开发工具文章标签：测试工具

本文链接：https://blog.csdn.net/LYP_Tom/article/details/125018540

版权

开发工具专栏收录该内容

1 篇文章 0 订阅

订阅专栏

代码注释规范

一、特殊文档块

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

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

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

C注释风格

/**
*  ...text...
* /

C++ 注释风格

///
///  ...text...
///

//!
//!  ...text...
//!

我们平时使用较多的

/******************************************
*  ...text...
******************************************/

/
///  ...text...
/

2.如果在配置文件中将JAVADOC_ AUTOBRIEF 设置为YES，可使用JavaDoc 注释块，并自动展开一个简明描述。
在这里插入图片描述
在出现第一个“.”处结束，后跟一个空格或空白行。这里有一一个例子：

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

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

};

二、成员之后放置文档

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

example：
QT注释风格：

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

JAVADOC ( C ）注释风格：

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

C++注释风格：

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

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

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

函数中可用 “@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. */);

警告:
这些块只能用于文档化成员和参数，无法用于文件，类，联合，结构，组，名字空间以及枚举，此外下面结构化命令(比如\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.
**********************************************/

在这里插入图片描述

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

在这里插入图片描述
使用HTML命令，可以是注释段落更清晰

三、组合

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

模块

成员组

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

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

//@{
...
//@}

或者

/*@{*/
...
/*@}*/

example：

//@{
/** Same documentation for both members. Details */
void funclInGroup1() ;
void func2InGroup1() ;
//@}

在一个块开始标记“@{”之前可以放置一个单独的注释块，而此块必须包含@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();
//@}

执行效果
在这里插入图片描述

子页面

在“模块”章节中简述添加结构的替代方法，为了更自然和方便地增加额外结构到页面中，可以使用\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".
*/