doxys是開源軟件, 文章最后給的鏈接里的doxys.exe是debug版本,還有個配置文件,感興趣的朋友可以打開鏈接下載,按照下面的方法使用即可。
一、更改配置:打開DoxySfile,設置INPUT(源碼路徑)、OUTPUT_DIRECTORY(輸出路徑)、OUTPUT_LANGUAGE(語言選擇----界面語言)
如果是中文界面,只要改變INPUT和OUT_DIRECTORY的路徑就可以。
二、生成文檔:進入MS-DOS,切換到doxys.exe所在的路徑,執(zhí)行doxys DoxySfile -m就可產生幫助文檔,不過都是html。
三、制作CHM文檔:進入到配置文件中的OUTPUT_DIRECTORY(輸出路徑)下,在common目錄,打開js.js,搜索一下“http://www.doxys.dk”,
將有這已經的代碼行注釋掉(這行在頁面上產生“產生 DoxyS”鏈接,它的直接結果就是產生doxys的英文幫助)。
最后單擊.hhc或.hhk或.hhp文件,在File菜單下點擊“compile”,就可以產生.chm文件。
四、其他:必須的安裝文件還有htmhtlp.exe.
附錄:編寫注釋規(guī)范
一、函數注釋:
/**
\brief
簡短注釋
\n
* @param[in] 輸入參數
* @param[out] 輸出參數
* @return 返回值
* @note 注解
* @par 示例
* @code 代碼
* @endcode
* @see 參見
* @deprecated 相關信息
也可以在@param后面直接跟參數
示例:函數OpenFile的注釋
/**
\brief file_文件
打開文件 \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);
二、變量注釋:
/** 成員變量描述 */
int m_Var;
三、宏定義注釋:
/** 定義說明 */
#define LOG_FILENAME "d:\\log\\debug.log"
在宏定義中我們也可以分組展示:就是在一組的宏定義前面和后面分別加注釋
前面加:
/** @name 文件名常量
* @{
*/
后面加:
/** @}*/ // 文件名常量
如下所示:
/** @name 文件名常量
* @{
*/
/** 日志文件名 */
#define LOG_FILENAME "d:\\log\\debug.log"
/** 數據文件名 */
#define DATA_FILENAME "d:\\data\\detail.dat"
/** 存檔文件名 */
#define BAK_FILENAME "d:\\data\\backup.dat"
/** @}*/ // 文件名常量
四、枚舉注釋:
/** 枚舉常量 */
typedef enum TDayOfWeek
{
SUN = 0, /**< 星期天 */
MON = 1, /**< 星期一 */
TUE = 2, /**< 星期二 */
WED = 3, /**< 星期三 */
THU = 4, /**< 星期四 */
FRI = 5, /**< 星期五 */
SAT = 6 /**< 星期六 */
}
五、類注釋:
1、類的簡短說明:放到類聲明(Yourclass.h)最前面
/*!\file
\brief Yourclass類封裝了對象的屬性及對屬性的操作
*/
.......
.......
class Yourclass{
.........
};
2、類的詳細說明:在類簡短說明下面
/** \file
\brief 每個CPerson類對象包含問題規(guī)定的對象屬性
* @author 作者
* @version 版本號
* @date 日期
在“誰養(yǎng)魚”問題中,每個對象包含屬性:國籍、顏色、寵物、飲料、香煙、房間號。不過CPerson并不關心屬性的含義。
屬性對CPerson來說只是序號和值。
*/
六、結構體/聯合體:
/** A test class. 結構體簡要說明. */
typedef struct TWeek
{
int a; //!< 星期天
int b;//!<星期一
int c; //!<星期二
};
下面的鏈接是doxys.exe、DoxySfile和htmlhelp.exe,doxys.exe是debug版本的比較大,DoxySfile是配置文件,如果搭建懶得寫,改改這個示例的配置文件就行,方法如上所示。
http://www.vdisk.cn/down/index/4361526A7291
Doxygen相關設置
首先在“Wizard”標簽的Project項進行如下設置:
項目名稱:將在最新的文檔首頁中顯示
源碼列表:選擇要生成文檔的源代碼或目錄,可以有多個文件或目錄形成一個列表。建議使用相對路徑,相對于當前目錄(也即當前配置文件所在的目錄)
遞歸掃描:如果需要對整個源碼目錄下的所有子目錄及文件生成文檔,請勾選本項
輸出目錄:設置最終生成的幫助文檔的存儲路徑,建議使用相對路徑
下一步,Mode項,根據需要設置文檔生成模式。
下一步,Output項,設置輸出格式,勾選HTML和“prepare for compressed HTML(.chm)”
然后切換到“Expert”標簽的“HTML”項,設置HTML和CHM相關的選項:
GENERATE_HTMLHELP:確保已經勾選了
CHM_FILE:最終生成的.chm的文件名,如“HkcProjectHelp.chm”。默認為“index.chm”。可以使用路徑,也可以使用相對路徑,相對于上面設置的輸出目錄的html目錄(建設使用上一級目錄,如“..\MyDoc.chm”)
HHC_LOCATION:chm 編譯器(hhc.exe)的全路徑。請指到
HTML Help Workshop 的安裝目錄的 hhc.exe 程序
CHM_INDEX_ENCODING:chm索引文件編碼,下面會講到,這里填“GBK”
編碼設置
編碼設置很重要,如果設置不當,生成的文檔會出現亂碼。因為 Doxygen 汲及的東西多,有好幾項編碼設置,所以需要認真對待,根據項目的實情情況設置。
所有高級設置(包括編碼設置)都在“Expert”標簽,重要的設置項如下:
Project/DOXYFILE_ENCODING:當前 Doxygen 配置文件本身的字符編碼,默認為UTF-8,一般不需要修改
Project/OUTPUT_LANGUAGE:輸出語言。這里是指Doxygen自己生成的導航、提示、幫助等文本的文字采用的語言。我們希望幫助文檔是全中文的,所以選擇Chinese
Input/INPUT_ENCODING:輸入文件的編碼。這里是指我們的源代碼文件本身的編碼。在Windows平臺一般是系統編碼(GBK),而Linux平臺一般是UTF-8。請用文本編輯器查看源文件的編碼。這里如果設置的不一致,源碼文件的注釋中所有非ASCII字符將在生成的文檔中變成亂碼。
HTMP/CHM_INDEX_ENCODING:這里設置Doxygen生成的CHM索引文件的編碼,以前是不能設置的,默認為UTF-8,而微軟的編譯器不能識別UTF-8編碼的索引文件,所以最終造成左邊目錄導航欄亂碼。我們設置它為GBK,這樣Doxygen將為我們生成GBK編碼的索引文件(.hhc、.hhk、.hhp)