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