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 eventn
   *            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
  1. mouse move event
  2. mouse click event
     More info about the click event.
  3. mouse double click event
• keyboard events
  1. key down event
  2. 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