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

程序文档，曾经是程序员的一个头痛问题。写一个程序文档，比较花时间，但不是很难；麻烦的是当程序修改后，程序文档也要跟着同步更新，否则文档和程序就要脱节，文档也就变成没用的东西了。

好在有许多好用的文档生成器来解决这个问题。目前比较流行的C++文档生成器是doxygen。
本文就简单的介绍一下doxygen的文档注释方法，以供初学者参考：

C++ 程序文档生成器介绍(doxygen)沐枫网志

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

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

*@{

*/

... 定义的内容 ...

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

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

/*
*@name分组说明文字

*@{

*/

... 定义的内容 ...

/**@}*/

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

/**简要说明文字*/

#define FLOAT float

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

#define MIN_UINT 0

/*
*分行的简要说明\n

*这是第二行的简要说明

*/

intb;

4.函数说明

/*
*简要的函数说明文字

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

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

*@return返回值说明

*/

intfunc(intparam1,intparam2);

/*
*打开文件\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
  1. mouse move event
  2. mouse click event
     More info about the click event.
  3. mouse double click event
• keyboard events
  1. key down event
  2. key up event

More text here.

代码示范：

/*
*@defgroupEXAMPLES自动注释文档范例
*@author沐枫
*@version1.0
*@date2004-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_NORMAL0
/**故障状态*/
#define SYS_FAULT1
/**警告状态*/
#define SYS_WARNNING2

/**@}*/ // 系统状态常量



/**枚举常量*/
typedef enum TDayOfWeek
{
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由于特殊的原因，这个函数可能会在将来的版本中取消。
*/
int OpenFile( const char * file_name, const char * file_mode);

/*
*读取文件
*@param[in]file文件编号，参见：::OpenFile
*@param[out]buffer用于存放读取的文件内容
*@param[in]len需要读取的文件长度
*@return返回读取文件的长度
*--1表示读取文件失败

*@pre\efile变量必须使用::OpenFile返回值
*@pre\ebuffer不能为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\efile变量必须使用::OpenFile返回值
*@see::OpenFile::ReadFile::CloseFile
*/
int WriteFile( int file, const char * buffer, int len);

/*
*关闭文件
*@paramfile文件编号，参见：::OpenFile
*@retval0为成功
*@retval-1表示失败

*@see::OpenFile::WriteFile::ReadFile
*@deprecated由于特殊的原因，这个函数可能会在将来的版本中取消。
*/
int CloseFile( int file);

/**@}*/ // 文件操作函数

/**@}*/ // 自动注释文档范例

生成的chm文档截图：



范例下载：
/Files/ly4cn/doxygen_example.rar

http://www.cnblogs.com/ly4cn/archive/2005/11/23/282637.html