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

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

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

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

C++
程序文档生成器介绍(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:\\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 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.

代码示范：


/*


* @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);




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




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

生成的chm文档截图：



范例下载：

/Files/ly4cn/doxygen_example.rar

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