Doxygen是基於GPL的開源項目,是一個非常優秀的文檔系統,當前支援在大多數unix(包括linux),windows家族,Mac系統上運行,完全支援C++, C, Java, IDLCorbaMicrosoft 家族)語言,部分支援PHPC#語言,輸出格式包括HTMLlatexRTFpsPDF、壓縮的HTMLunix manpageDoxygen軟體可以從這裡下載,軟體本身用法非常簡單。這裡不做介紹,下面主要是代碼中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);


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


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

    全站熱搜

    立你斯 發表在 痞客邦 留言(1) 人氣()