Doxygen c++ 注释风格

Doxygen

---

若想用 Doxygen 生成漂亮的文档，我们必须在以下几个地方添加 Doxygen 风格的注释：

1. 文件头（包括 头文件 .h 和 源文件 .cpp）

   主要用于版权声明，描述本文件的功能，以及作者、版本信息等。

2. 类的定义

   主要用于描述类的功能，同时也可以包含使用方法、注意事项的 brief description。

3. 类的成员变量定义

   对该成员变量进行 brief description。

4. 类的成员函数定义

   对该成员函数的功能进行 brief description。

5. 函数实现

   对函数的功能、参数、返回值、需要注意的问题、相关说明等进行 detailed description。

C++ Comment Style

---

Doxygen 支持多种注释风格，比如 JavaDoc-like 风格，Qt 风格等。在写 C++ 代码时，我们应该遵守 C++ 的行注释风格，所谓行注释风格，是指一般 C++ 程序员避免使用 C 风格的注释符号 /* */，而是使用 3 个连续的 / 作为注释的开头。除了这个区别之外，其他部分和 JavaDoc 风格类似：

• 一个对象的 brief description 用单行的 /// 开始，并且写在代码前面。一般 brief 写在头文件中，对象的声明之前。

• 一个对象的 detailed description 用多于两行的 /// 开始，并且写在代码前面。如果注释长度不足两行，第二行的开头仍要写出。一般 detailed 写在源文件中，对象的定义之前。

• 如果一段代码既是声明也是定义，则 brief 和 detailed 写在一起。使用 \brief 命令，并且使用空行将两者分开。一般 brief 写在头文件中，对象的声明之前。

  1 2 3 4

  /// \brief A brief description. /// /// A detailed description, it /// should be 2 line at least.

下面是代码模板：

License

使用 DoxygenToolKit 自动生成的 Lisence 即可。

File header

---

1 2 3 4 5 6 7 8

/// \file file_name.h /// \brief Head file for class Ctest. /// /// A detailed file description. /// /// \author author_name /// \version version_number /// \date xxxx-xx-xx

Namespace

namespace 的注释方式：

1 2 3 4 5 6 7 8

/// \brief A brief namespace description. /// /// A detailed namespace description, it /// should be 2 lines at least. namespace test { }

Class

class 的定义和声明都在头文件中，所以使用下面这种 brief 和 detailed 结合的方式：

1 2 3 4 5 6 7 8

/// \brief A brief class description. /// /// A detailed calss description, it /// should be 2 lines at least. class test { }

member function

对于成员函数，

• 若是在头文件的声明处，使用 brief

• 若是在源文件的定义处，使用 detailed

• 若是在头文件处，声明和定义重合，使用 brief + detailed

member variable

对于成员变量，在行末使用 ///<。

Function

brief:

单行的 /// 注释：

1	/// A brief function description.

detailed:

至少两行 /// 的注释：

1 2	/// This is the detailed description, it /// should be 2 lines at least.

在 detailed description 中还可以添加一些 structural command，常用的有 \param、\return、\see、\note、\warning 等：

1 2 3 4 5 6 7 8 9

/// This is the detailed description, it /// should be 2 lines at least. /// /// \param p1 Brief description for p1 /// \param p2 Brief description for p2 /// \return Brief description for return value /// \note something to note. /// \warning Warning. /// \see See-also

brief + detailed:

如果函数声明和定义重合，则 brief 和 detailed 合在一起，并且使用 \brief 命令，格式如下：

1 2 3 4 5 6 7 8 9

/// \brief A brief function description. /// /// A detailed description, it /// should be 2 lines at least. /// /// \param p1 Description for p1. /// \param p2 Description for p2. /// \return Description for return value. bool test(int n1, char c1);

在 Doxgyen 的 manual 里面有：

Unlike most other documentation systems, doxygen also allows you to put the documentation of members (including global functions) in front of the definition. This way the documentation can be placed in the source file instead of the header file. This keeps the header file compact, and allows the implementer of the members more direct access to the documentation. As a compromise the brief description could be placed before the declaration and the detailed description before the member definition.

Doxygen 允许注释出现在对象的定义之前，所以我们可以将注释写在源文件中，而不是头文件中。这样做的好处是使头文件更加紧凑、代码的实现者阅读起来也更加直观。所以我们采用的方案是：

• 在函数声明前写 brief，在函数定义前写 detailed。

• 对于 inline 函数，使用 brief，尽量保持简洁，不要多于一行。

Variable

变量一般使用 ///< 方式即可：

1 2	int m_a; ///< brief description for variable m_a double m_b; ///< brief description for variable m_b

如果需要进行详细描述，则采用类似函数注释的方法（brief + detailed）：

1 2 3 4 5

/// \brief A brief description. /// /// A detailed description, it /// should be 2 lines at least. float m_c;

Enum & Struct

类似于 Variable 的注释方式：

1 2 3 4 5 6 7 8 9 10

/// \brief A brief description. /// /// A detailed description, it /// should be 2 lines at least. enum Tenum { em_1; ///< enum value em_1 em_2; ///< enum value em_2 em_3; ///< enum value em_3 } emVar; ///< enum variable.

Others

TODO 命令：

1 2	/// \todo Task1 to do /// \todo Task2 to do

BUG 命令：

1 2	/// \bug Bug1 to be fixed /// \bug Bug2 to be fixed

代码示例：

///
///
/// Copyright (C), 2015-2017, ***** Tech.Co.Ltd.
/// All rights reserved.
/// \file text.h  文件名
/// \author 作者
/// \version 版本号
/// \date 日期
/// \brief 头文件概述
///
/// 开始文件详细概述
/// Description:    用于详细说明此程序文件完成的主要功能.
/// Function List:  主要函数列表,每条记录应包括函数名及功能简要说明.
/// History:        修改历史记录列表,每条修改记录应包括修改日期、修改
///                 者及修改内容简述.
///                
///        David    96 / 10 / 12     1.0     build this moudle
///
///

#pragma once  
/// \brief 命名空间的简单概述   
///   
///命名空间的详细概述  
namespace text
{

}

/// \brief Text的doxygen测试  
///  
/// 详细概述作doxygen测试用  
class Text
{
public:
	Text(void);
	~Text(void);
	/// \brief 函数简要说明-测试函数 1 

	/// 函数详细说明，这里写函数的详细说明信息，说明可以换行  
	/// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行  
	/// ，详细说明之前不需要任何标识符  
	///
	/// \param n1 参数1说明  
	/// \param c2 参数2说明  
	/// \return 返回说明  
	bool text1(int n1, Text c2);
	/// \brief 函数简要说明-测试函数  2
	///   
	/// 函数详细说明，这里写函数的详细说明信息，说明可以换行  
	/// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行  
	/// ，详细说明之前不需要任何标识符  
	///
	/// \param n1 参数1说明  
	/// \param c2 参数2说明  
	/// \return 返回说明  
	bool text2(int n1, Text c2);
	///  \brief 函数简要说明-测试函数  3
	///   
	/// 函数详细说明，这里写函数的详细说明信息，说明可以换行  
	/// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行  
	/// ，详细说明之前不需要任何标识符  
	///
	/// \param n1 参数1说明  
	/// \param c2 参数2说明  
	/// \return 返回说明  
	bool text3(int n1, Text c2);
	/// \brief 函数说明-测试函数 4  

	/// 函数详细说明，这里写函数的详细说明信息，说明可以换行  
	/// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行  
	/// ，详细说明之前不需要任何标识符  
	///
	/// \param n1 参数1说明  
	/// \param c2 参数2说明  
	/// \return 返回说明  
	/// \see text3 text2 text  
	bool text4(int n1, Text c2);

	int ma;     ///< 成员变量1ma说明  
	double mb; ///< 成员变量2mb说明  

				/// \brief 成员变量mc简要说明  
				///  
				/// 成员变量mc的详细说明，这里可以对变量进行  
				///详细的说明和描述，具体方法和函数的标注是一样的  
	float mc;

	/// \brief xxx枚举变量的简要说明  
	///  
	/// xxx枚举变量的详细说明--枚举变量的详细说明和函数的详细说明  
	///的写法是一致的。每个枚举变量下可以进行单独说明  
	enum UrlTableErrors
	{
		EM_1,///< 枚举值1的说明  
		EM_2,///< 枚举值2的说明  
		EM_3 ///< 枚举值3的说明  
	};
};

/// \brief A brief class description.
///
/// A detailed calss description, it
/// should be 2 lines at least.
class test
{

}