2024年4月26日发(作者：)

C++ 程序文档生成器介绍(doxygen)

程序文档，曾经是程序员的一个头痛问题。写一个程序文档，比较花时间，但不是很难；麻烦的

是当程序修改后，程序文档也要跟着同步更新，否则文档和程序就要脱节，文档也就变成没用的

东西了。

好在有许多好用的文档生成器来解决这个问题。目前比较流行的C++文档生成器是doxygen。

本文就简单的介绍一下doxygen的文档注释方法，以供初学者参考：

1. 模块定义（单独显示一页）

/*

* @defgroup 模块名 模块的说明文字

* @{

*/

... 定义的内容 ...

/** @} */ // 模块结尾

2. 分组定义（在一页内分组显示）

/*

* @name 分组说明文字

* @{

*/

... 定义的内容 ...

/** @} */

3. 变量、宏定义、类型定义简要说明

/** 简要说明文字 */

#define FLOAT float

/** @brief 简要说明文字（在前面加 @brief 是标准格式）

#define MIN_UINT 0

*/

/*

* 分行的简要说明 n

* 这是第二行的简要说明

*/

int b;

4. 函数说明

/*

* 简要的函数说明文字

* @param [in] param1 参数1说明

* @param [out] param2 参数2说明

* @return 返回值说明

*/

int func(int param1, int param2);

/*

* 打开文件 n

* 文件打开成功后，必须使用 ::CloseFile 函数关闭。

* @param[in] file_name 文件名字符串

* @param[in] file_mode 文件打开模式字符串，可以由以下几个模块组合而

成：

* - r 读取

* - w 可写

* - a 添加

* - t 文本模式(不能与 b 联用)

* - b 二进制模式(不能与 t 联用)

* @return 返回文件编号

* - -1 表示打开文件失败

* @note 文件打开成功后，必须使用 ::CloseFile 函数关闭

* @par 示例:

* @code

// 用文本只读方式打开文件

int f = OpenFile("d:", "rt");

* @endcode

* @see ::ReadFile ::WriteFile ::CloseFile

* @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。

*/

int OpenFile(const char* file_name, const char* file_mode);