程序文檔，曾經(jīng)是程序員的一個(gè)頭痛問(wèn)題。寫(xiě)一個(gè)程序文檔，比較花時(shí)間，但不是很難；麻煩的是當程序修改后，程序文檔也要跟著(zhù)同步更新，否則文檔和程序就要脫節，文檔也就變成沒(méi)用的東西了。
好在有許多好用的文檔生成器來(lái)解決這個(gè)問(wèn)題。目前比較流行的C++文檔生成器是doxygen。
本文就簡(jiǎn)單的介紹一下doxygen的文檔注釋方法，以供初學(xué)者參考：
C++ 程序文檔生成器介紹(doxygen) 沐楓網(wǎng)志
1. 模塊定義（單獨顯示一頁(yè)）
/*
* @defgroup 模塊名 模塊的說(shuō)明文字
* @{
*/
... 定義的內容 ...
/** @} */ // 模塊結尾
2. 分組定義（在一頁(yè)內分組顯示）
/*
* @name 分組說(shuō)明文字
* @{
*/
... 定義的內容 ...
/** @} */
3. 變量、宏定義、類(lèi)型定義簡(jiǎn)要說(shuō)明
/** 簡(jiǎn)要說(shuō)明文字 */
#define FLOAT float
/** @brief 簡(jiǎn)要說(shuō)明文字（在前面加 @brief 是標準格式） */
#define MIN_UINT 0
/*
* 分行的簡(jiǎn)要說(shuō)明 \n
* 這是第二行的簡(jiǎn)要說(shuō)明
*/
int b;
4. 函數說(shuō)明
/*
* 簡(jiǎn)要的函數說(shuō)明文字
* @param [in] param1 參數1說(shuō)明
* @param [out] param2 參數2說(shuō)明
* @return 返回值說(shuō)明
*/
int func(int param1, int param2);
/*
* 打開(kāi)文件 \n
* 文件打開(kāi)成功后，必須使用 ::CloseFile 函數關(guān)閉。
* @param[in] file_name 文件名字符串
* @param[in] file_mode 文件打開(kāi)模式字符串，可以由以下幾個(gè)模塊組合而成：
* - r 讀取
* - w 可寫(xiě)
* - a 添加
* - t 文本模式(不能與 b 聯(lián)用)
* - b 二進(jìn)制模式(不能與 t 聯(lián)用)
* @return 返回文件編號
* - -1 表示打開(kāi)文件失敗
* @note 文件打開(kāi)成功后，必須使用 ::CloseFile 函數關(guān)閉
* @par 示例:
* @code
// 用文本只讀方式打開(kāi)文件
int f = OpenFile("d:\\test.txt", "rt");
* @endcode
* @see ::ReadFile ::WriteFile ::CloseFile
* @deprecated 由于特殊的原因，這個(gè)函數可能會(huì )在將來(lái)的版本中取消。
*/
int OpenFile(const char* file_name, const char* file_mode);
5. 枚舉類(lèi)型定義
/** 枚舉常量 */
typedef enum TDayOfWeek
{
SUN = 0, /**< 星期天（注意，要以 “<” 小于號開(kāi)頭） */
MON = 1, /**< 星期一 */
TUE = 2, /**< 星期二 */
WED = 3, /**< 星期三 */
THU = 4, /**< 星期四 */
FRI = 5, /**< 星期五 */
SAT = 6 /**< 星期六 */
}
/** 定義類(lèi)型 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 自動(dòng)注釋文檔范例
* @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 系統狀態(tài)常量
* @{
*/
/**//** 正常狀態(tài) */
#define SYS_NORMAL 0
/**//** 故障狀態(tài) */
#define SYS_FAULT 1
/**//** 警告狀態(tài) */
#define SYS_WARNNING 2
/**//** @}*/ // 系統狀態(tài)常量
/**//** 枚舉常量 */
typedef enum TDayOfWeek
{
SUN = 0, /**//**< 星期天 */
MON = 1, /**//**< 星期一 */
TUE = 2, /**//**< 星期二 */
WED = 3, /**//**< 星期三 */
THU = 4, /**//**< 星期四 */
FRI = 5, /**//**< 星期五 */
SAT = 6 /**//**< 星期六 */
}
/**//** 定義類(lèi)型 TEnumDayOfWeek */
TEnumDayOfWeek;
/**//** 定義類(lèi)型 PEnumDayOfWeek */
typedef TEnumDayOfWeek* PEnumDayOfWeek;
/**//** 定義枚舉變量 enum1 */
TEnumDayOfWeek enum1;
/**//** 定義枚舉指針變量 enum2 */
PEnumDayOfWeek p_enum2;
/**//*
* @defgroup FileUtils 文件操作函數
* @{
*/
/**//*
* 打開(kāi)文件 \n
* 文件打開(kāi)成功后，必須使用 ::CloseFile 函數關(guān)閉。
* @param[in] file_name 文件名字符串
* @param[in] file_mode 文件打開(kāi)模式字符串，可以由以下幾個(gè)模塊組合而成：
* - r 讀取
* - w 可寫(xiě)
* - a 添加
* - t 文本模式(不能與 b 聯(lián)用)
* - b 二進(jìn)制模式(不能與 t 聯(lián)用)
* @return 返回文件編號
* - -1 表示打開(kāi)文件失敗
* @note 文件打開(kāi)成功后，必須使用 ::CloseFile 函數關(guān)閉
* @par 示例:
* @code
// 用文本只讀方式打開(kāi)文件
int f = OpenFile("d:\\test.txt", "rt");
* @endcode
* @see ::ReadFile ::WriteFile ::CloseFile
* @deprecated 由于特殊的原因，這個(gè)函數可能會(huì )在將來(lái)的版本中取消。
*/
int OpenFile(const char* file_name, const char* file_mode);
/**//*
* 讀取文件
* @param[in] file 文件編號，參見(jiàn)：::OpenFile
* @param[out] buffer 用于存放讀取的文件內容
* @param[in] len 需要讀取的文件長(cháng)度
* @return 返回讀取文件的長(cháng)度
* - -1 表示讀取文件失敗
* @pre \e file 變量必須使用 ::OpenFile 返回值
* @pre \e buffer 不能為 NULL
* @see ::OpenFile ::WriteFile ::CloseFile
*/
int ReadFile(int file, char* buffer, int len);
/**//*
* 寫(xiě)入文件
* @param[in] file 文件編號，參見(jiàn)：::OpenFile
* @param[in] buffer 用于存放將要寫(xiě)入的文件內容
* @param[in] len 需要寫(xiě)入的文件長(cháng)度
* @return 返回寫(xiě)入的長(cháng)度
* - -1 表示寫(xiě)入文件失敗
* @pre \e file 變量必須使用 ::OpenFile 返回值
* @see ::OpenFile ::ReadFile ::CloseFile
*/
int WriteFile(int file, const char* buffer, int len);
/**//*
* 關(guān)閉文件
* @param file 文件編號，參見(jiàn)：::OpenFile
* @retval 0 為成功
* @retval -1 表示失敗
* @see ::OpenFile ::WriteFile ::ReadFile
* @deprecated 由于特殊的原因，這個(gè)函數可能會(huì )在將來(lái)的版本中取消。
*/
int CloseFile(int file);
/**//** @}*/ // 文件操作函數
/**//** @}*/ // 自動(dòng)注釋文檔范例
