C++ 程序文档生成器介绍(doxygen)
程序文档，曾经是程序员的一个头痛问题。写一个程序文档，比较花时间，但不是很难；麻烦的是当程序修改后，程序文档也要跟着同步更新，否则文档和程序就要脱节，文档也就变成没用的东西了。
好在有许多好用的文档生成器来解决这个问题。目前比较流行的C++文档生成器是doxygen。
本文就简单的介绍一下doxygen的文档注释方法，以供初学者参考：
C++
程序文档生成器介绍(doxygen)沐枫网志
1.模块定义（单独显示一页）
/*
*@defgroup模块名模块的说明文字
*@defgroup模块名模块的说明文字
*@{
*/
... 定义的内容 ...
/**@}*/ // 模块结尾
2.分组定义（在一页内分组显示）
/*
*@name分组说明文字
*@name分组说明文字
*@{
*/
... 定义的内容 ...
/**@}*/
3.变量、宏定义、类型定义简要说明
/**简要说明文字*/
#define FLOAT float
/**@brief 简要说明文字（在前面加 @brief 是标准格式）*/
#define MIN_UINT 0
/*
*分行的简要说明\n
*分行的简要说明\n
*这是第二行的简要说明
*/
intb;
4.函数说明
/*
*简要的函数说明文字
*简要的函数说明文字
*@param[in]param1参数1说明
*@param[out]param2参数2说明
*@return返回值说明
*/
intfunc(intparam1,intparam2);
/*
*打开文件\n
*打开文件\n
*文件打开成功后，必须使用::CloseFile函数关闭。
*@param[in]file_name文件名字符串
*@param[in]file_mode文件打开模式字符串，可以由以下几个模块组合而成：
*-r读取
*-w可写
*-a添加
*-t文本模式(不能与b联用)
*-b二进制模式(不能与t联用)
*@return返回文件编号
*--1表示打开文件失败
*@note文件打开成功后，必须使用::CloseFile函数关闭
*@par示例:
*@code
//用文本只读方式打开文件
intf=OpenFile("d:\\test.txt","rt");
*@endcode
*@see::ReadFile::WriteFile::CloseFile
*@deprecated由于特殊的原因，这个函数可能会在将来的版本中取消。
*/
intOpenFile(constchar*file_name,constchar*file_mode);
5.枚举类型定义
/**枚举常量*/
typedefenumTDayOfWeek
{
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 event\n
* 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\n
* 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.
代码示范：
/*
*@defgroupEXAMPLES自动注释文档范例
*@author沐枫
*@version1.0
*@date2004-2005
*@{
*/
/*
*@name文件名常量
*@{
*/
/**日志文件名*/
#defineLOG_FILENAME"d:\\log\\debug.log"
/**数据文件名*/
#defineDATA_FILENAME"d:\\data\\detail.dat"
/**存档文件名*/
#defineBAK_FILENAME"d:\\data\\backup.dat"
/**@}*///文件名常量
/*
*@name系统状态常量
*@{
*/
/**正常状态*/
#defineSYS_NORMAL0
/**故障状态*/
#defineSYS_FAULT1
/**警告状态*/
#defineSYS_WARNNING2
/**@}*///系统状态常量
/**枚举常量*/
typedefenumTDayOfWeek
{
SUN=0,/**<星期天*/
MON=1,/**<星期一*/
TUE=2,/**<星期二*/
WED=3,/**<星期三*/
THU=4,/**<星期四*/
FRI=5,/**<星期五*/
SAT=6/**<星期六*/
}
/**定义类型TEnumDayOfWeek*/
TEnumDayOfWeek;
/**定义类型PEnumDayOfWeek*/
typedefTEnumDayOfWeek*PEnumDayOfWeek;
/**定义枚举变量enum1*/
TEnumDayOfWeekenum1;
/**定义枚举指针变量enum2*/
PEnumDayOfWeekp_enum2;
/*
*@defgroupFileUtils文件操作函数
*@{
*/
/*
*打开文件\n
*文件打开成功后，必须使用::CloseFile函数关闭。
*@param[in]file_name文件名字符串
*@param[in]file_mode文件打开模式字符串，可以由以下几个模块组合而成：
*-r读取
*-w可写
*-a添加
*-t文本模式(不能与b联用)
*-b二进制模式(不能与t联用)
*@return返回文件编号
*--1表示打开文件失败
*@note文件打开成功后，必须使用::CloseFile函数关闭
*@par示例:
*@code
//用文本只读方式打开文件
intf=OpenFile("d:\\test.txt","rt");
*@endcode
*@see::ReadFile::WriteFile::CloseFile
*@deprecated由于特殊的原因，这个函数可能会在将来的版本中取消。
*/
intOpenFile(constchar*file_name,constchar*file_mode);
/*
*读取文件
*@param[in]file文件编号，参见：::OpenFile
*@param[out]buffer用于存放读取的文件内容
*@param[in]len需要读取的文件长度
*@return返回读取文件的长度
*--1表示读取文件失败
*@pre\efile变量必须使用::OpenFile返回值
*@pre\ebuffer不能为NULL
*@see::OpenFile::WriteFile::CloseFile
*/
intReadFile(intfile,char*buffer,intlen);
/*
*写入文件
*@param[in]file文件编号，参见：::OpenFile
*@param[in]buffer用于存放将要写入的文件内容
*@param[in]len需要写入的文件长度
*@return返回写入的长度
*--1表示写入文件失败
*@pre\efile变量必须使用::OpenFile返回值
*@see::OpenFile::ReadFile::CloseFile
*/
intWriteFile(intfile,constchar*buffer,intlen);
/*
*关闭文件
*@paramfile文件编号，参见：::OpenFile
*@retval0为成功
*@retval-1表示失败
*@see::OpenFile::WriteFile::ReadFile
*@deprecated由于特殊的原因，这个函数可能会在将来的版本中取消。
*/
intCloseFile(intfile);
/**@}*///文件操作函数
/**@}*///自动注释文档范例