立你斯學習記錄

Doxygen是基於GPL的開源項目，是一個非常優秀的文檔系統，當前支援在大多數unix（包括linux），windows家族，Mac系統上運行，完全支援C++, C, Java, IDL（Corba和Microsoft 家族）語言，部分支援PHP和C#語言，輸出格式包括HTML、latex、RTF、ps、PDF、壓縮的HTML和unix manpage，Doxygen軟體可以從這裡下載，軟體本身用法非常簡單。這裡不做介紹，下面主要是代碼中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 minidxer
* @version 1.0
* @date 2007-2008
* @{
*/

/*
* @name 檔案名常量
* @{
*/

/** 日誌檔案名 */
#define LOG_FILENAME “c:\\log\\debug.log”
/** 資料檔案名 */
#define DATA_FILENAME “c:\\data\\detail.dat”
/** 存檔檔案名 */
#define BAK_FILENAME “c:\\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(”c:\\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);

/** @}*/ // 檔操作函數

/** @}*/ // 自動注釋文檔範例