程序文档，曾经是程序员的一个头痛问题。写一个程序文档，比较花时间，但不是很难；麻烦的是当程序修改后，程序文档也要跟着同步更新，否则文档和程序就要脱节，文档也就变成没用的东西了。
好在有许多好用的文档生成器来解决这个问题。目前比较流行的C++文档生成器是doxygen。
本文就简单的介绍一下doxygen的文档注释方法，以供初学者参考：
C++ 程序文档生成器介绍(doxygen) 沐枫网志
1. 模块定义（单独显示一页）
/*
* @defgroup 模块名 模块的说明文字
* @defgroup 模块名 模块的说明文字
* @{
*/
... 定义的内容 ...
/** @} */ // 模块结尾
2. 分组定义（在一页内分组显示）
/*
* @name 分组说明文字
* @name 分组说明文字
* @{
*/
... 定义的内容 ...
/** @} */
3. 变量、宏定义、类型定义简要说明
/** 简要说明文字 */
#define FLOAT float
/** @brief 简要说明文字（在前面加 @brief 是标准格式） */
#define MIN_UINT 0
/*
* 分行的简要说明 n
* 分行的简要说明 n
* 这是第二行的简要说明
*/
int b;
4. 函数说明
/*
* 简要的函数说明文字
* 简要的函数说明文字
* @param [in] param1 参数1说明
* @param [out] param2 参数2说明
* @return 返回值说明
*/
int func(int param1, int param2);
/*
* 打开文件 n
* 打开文件 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:\test.txt", "rt");
* @endcode
* @see ::ReadFile ::WriteFile ::CloseFile
* @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。
*/
int OpenFile(const char* file_name, const char* file_mode);
5. 枚举类型定义
/** 枚举常量 */
typedef enum TDayOfWeek
{
SUN = 0, /**” 小于号开头） */
MON = 1, /**
TUE = 2, /**
WED = 3, /**
THU = 4, /**
FRI = 5, /**
SAT = 6 /**
}
/** 定义类型 TEnumDayOfWeek */
TEnumDayOfWeek;
6. 项目符号标记
/*
* A list of events:
* - mouse events
* -# mouse move event
* -# mouse click eventn
* More info about the click event.
* -# mouse double click event
* - keyboard events
* -# key down event
* -# key up event
*
* More text here.
*/
* A list of events:
* - mouse events
* -# mouse move event
* -# mouse click eventn
* More info about the click event.
* -# mouse double click event
* - keyboard events
* -# key down event
* -# key up event
*
* More text here.
*/
结果为：
A list of events:
- mouse events
- mouse move event
- mouse click event
More info about the click event. - mouse double click event
- keyboard events
- key down event
- key up event
More text here.
代码示范： 
/**//*
* @defgroup EXAMPLES 自动注释文档范例
* @author 沐枫
* @version 1.0
* @date 2004-2005
* @{
*/
/**//*
* @name 文件名常量
* @{
*/
/**//** 日志文件名 */
#define LOG_FILENAME "d:\log\debug.log"
/**//** 数据文件名 */
#define DATA_FILENAME "d:\data\detail.dat"
/**//** 存档文件名 */
#define BAK_FILENAME "d:\data\backup.dat"
/**//** @}*/ // 文件名常量
/**//*
* @name 系统状态常量
* @{
*/
/**//** 正常状态 */
#define SYS_NORMAL 0
/**//** 故障状态 */
#define SYS_FAULT 1
/**//** 警告状态 */
#define SYS_WARNNING 2
/**//** @}*/ // 系统状态常量
/**//** 枚举常量 */
typedef enum TDayOfWeek
{
SUN = 0, /**//***/
MON = 1, /**//***/
TUE = 2, /**//***/
WED = 3, /**//***/
THU = 4, /**//***/
FRI = 5, /**//***/
SAT = 6 /**//***/
}
/**//** 定义类型 TEnumDayOfWeek */
TEnumDayOfWeek;
/**//** 定义类型 PEnumDayOfWeek */
typedef TEnumDayOfWeek* PEnumDayOfWeek;
/**//** 定义枚举变量 enum1 */
TEnumDayOfWeek enum1;
/**//** 定义枚举指针变量 enum2 */
PEnumDayOfWeek p_enum2;
/**//*
* @defgroup FileUtils 文件操作函数
* @{
*/
/**//*
* 打开文件 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:\test.txt", "rt");
* @endcode
* @see ::ReadFile ::WriteFile ::CloseFile
* @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。
*/
int OpenFile(const char* file_name, const char* file_mode);
/**//*
* 读取文件
* @param[in] file 文件编号，参见：::OpenFile
* @param[out] buffer 用于存放读取的文件内容
* @param[in] len 需要读取的文件长度
* @return 返回读取文件的长度
* - -1 表示读取文件失败
* @pre e file 变量必须使用 ::OpenFile 返回值
* @pre e buffer 不能为 NULL
* @see ::OpenFile ::WriteFile ::CloseFile
*/
int ReadFile(int file, char* buffer, int len);
/**//*
* 写入文件
* @param[in] file 文件编号，参见：::OpenFile
* @param[in] buffer 用于存放将要写入的文件内容
* @param[in] len 需要写入的文件长度
* @return 返回写入的长度
* - -1 表示写入文件失败
* @pre e file 变量必须使用 ::OpenFile 返回值
* @see ::OpenFile ::ReadFile ::CloseFile
*/
int WriteFile(int file, const char* buffer, int len);
/**//*
* 关闭文件
* @param file 文件编号，参见：::OpenFile
* @retval 0 为成功
* @retval -1 表示失败
* @see ::OpenFile ::WriteFile ::ReadFile
* @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。
*/
int CloseFile(int file);
/**//** @}*/ // 文件操作函数
/**//** @}*/ // 自动注释文档范例
/**//* * @defgroup EXAMPLES 自动注释文档范例 * @author 沐枫 * @version 1.0 * @date 2004-2005 * @{ *//**//* * @name 文件名常量 * @{ *//**//** 日志文件名 */#define LOG_FILENAME "d:\log\debug.log"/**//** 数据文件名 */#define DATA_FILENAME "d:\data\detail.dat"/**//** 存档文件名 */#define BAK_FILENAME "d:\data\backup.dat"/**//** @}*/ // 文件名常量/**//* * @name 系统状态常量 * @{ */ /**//** 正常状态 */#define SYS_NORMAL 0/**//** 故障状态 */#define SYS_FAULT 1/**//** 警告状态 */#define SYS_WARNNING 2/**//** @}*/ // 系统状态常量/**//** 枚举常量 */typedef enum TDayOfWeek{ SUN = 0, /**//***/ MON = 1, /**//***/ TUE = 2, /**//***/ WED = 3, /**//***/ THU = 4, /**//***/ FRI = 5, /**//***/ SAT = 6 /**//***/}/**//** 定义类型 TEnumDayOfWeek */TEnumDayOfWeek; /**//** 定义类型 PEnumDayOfWeek */typedef TEnumDayOfWeek* PEnumDayOfWeek; /**//** 定义枚举变量 enum1 */TEnumDayOfWeek enum1; /**//** 定义枚举指针变量 enum2 */PEnumDayOfWeek p_enum2; /**//* * @defgroup FileUtils 文件操作函数 * @{ *//**//* * 打开文件 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:\test.txt", "rt"); * @endcode * @see ::ReadFile ::WriteFile ::CloseFile * @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。 */int OpenFile(const char* file_name, const char* file_mode);/**//* * 读取文件 * @param[in] file 文件编号，参见：::OpenFile * @param[out] buffer 用于存放读取的文件内容 * @param[in] len 需要读取的文件长度 * @return 返回读取文件的长度 * - -1 表示读取文件失败 * @pre e file 变量必须使用 ::OpenFile 返回值 * @pre e buffer 不能为 NULL * @see ::OpenFile ::WriteFile ::CloseFile */int ReadFile(int file, char* buffer, int len);/**//* * 写入文件 * @param[in] file 文件编号，参见：::OpenFile * @param[in] buffer 用于存放将要写入的文件内容 * @param[in] len 需要写入的文件长度 * @return 返回写入的长度 * - -1 表示写入文件失败 * @pre e file 变量必须使用 ::OpenFile 返回值 * @see ::OpenFile ::ReadFile ::CloseFile */int WriteFile(int file, const char* buffer, int len);/**//* * 关闭文件 * @param file 文件编号，参见：::OpenFile * @retval 0 为成功 * @retval -1 表示失败 * @see ::OpenFile ::WriteFile ::ReadFile * @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。 */int CloseFile(int file);/**//** @}*/ // 文件操作函数/**//** @}*/ // 自动注释文档范例
