Doxygen心得
技術 2008-10-08 16:24:54 閱讀2524 評論0 字號：大中小 訂閱
幾年前，看過幾個開源項目的文檔，發現每個開源都會有一個幫助文件，感覺注釋非常詳細。當時就感慨開源項目的人精力充沛。後發覺注釋和代碼有很多相似之處，經過研究，了解到了doxygen。正巧前段時間公司要程序生成文檔，以前很多都是都是手工完成的。經過交流，我們修改了部分源代碼的注釋，同時我寫一個幫助，放到這裏。
doxygen是一款源代碼幫助文檔生成工具。依靠源代碼中的注釋，doxygen可以輕鬆的生成多種格式的幫助文檔，供開發者閱讀。
doxygen的使用方法很簡單：
第一步，需要修改源代碼文件，規範現有注釋。為了使注釋輕鬆智能的變成可讀的文檔。doxygen規定了自己的注釋格式，這樣太才可以解析。最常用的注釋格式是：
/**
there is comment.
*/或
/*!
there is comment.
*/
同時，為了區分注釋的用途，doxygen定義了很多關鍵字，用來標識注釋描述的代碼段或者用途。常用@後麵跟用途關鍵字來標識，關鍵字在doxygen 附帶的幫助文件中有很詳細的解析(在Special Commands這一節中)，這裏就不在累贅了。這裏有一個地方需要注意一下，描述的各個分段之間最好用tab空開，用空格有的時候會出現問題。
如：
/**
* @brief 這是一個函數
* @param a 參數一
* @param b 參數二
* @return 無返回值
*/
void fooFun(int a, int b);
第二步，建立doxygen配置文件。doxygen執行的時候需要一個配置文件，即每生成一個chm都會有一個配置文件來進行生成工程具體信息的描述。手工編寫那個配置文件比較繁瑣，還好doxygen隨身附帶了一個DoxyWizard，利用這個向導。你可以方便的配置想要的信息。注意 DoxyWizard僅僅是一個界麵，他最終編譯的時候還是執行了doxygen.exe，傳輸時不要隻拷貝這一個文件。
打開DoxyWizard，會發現DoxyWizard分成了三個區域。
在step1中有三個按鈕。
按鈕[Wizard...]裏麵配置項目的一些基本信息
按鈕[Expert...]包含高級配置信息
按鈕[Load...]加載一個doxygen配置文件
在step1中，有個最重要的設置就是在[Wizard...]的Project頁麵中的Source code directory選項。把這個指向你的源代碼文件路徑。Scan recursively表示是否遞歸遍曆。
step1完成之後，你必須要保存一下doxygen配置文件。隻需要點擊step2的保存按鈕即可。
step3中的工作目錄，也就是doxygen最終生成的幫助文檔(chm)的存放路徑。
最後，點擊step4中的[Start]按鈕即可。
在Output列表中。是doxygen生成編譯時生成的信息。注意上麵已經提到過，DoxyWizard和doxygen是兩個不同的進程，所以在 DoxyWizard輸出日誌的時候可能會有停頓。具體顯示時候的通信機製我沒有看，但這和機器或者doxygen本身的代碼沒有關係。
我在這裏主要講一些基本常用的屬性，很多我覺得意義不大的，請自行研究，這裏就不過多解釋了。
在[Wizard...]中沒有特別複雜的地方，稍微看一眼便知。
在[Expert...]按鈕中，有一個tab頁，下麵來逐一解釋：
Project頁麵，主要包括項目的基本配置。
TAB_SIZE 主要是幫助文件中代碼的縮進尺寸，譬如@code和@endcode段中代碼的排版，建議符合習慣，設置成4。
OPTIMIZE_OUTPUT_FOR_C 這個選項選擇後，生成文檔的一些描述性名稱會發生變化，主要是符合C習慣。如果是純C代碼，建議選擇。
SUBGROUPING這個選項選擇後，輸出將會按類型分組。
Build頁麵，這個頁麵是生成幫助信息中比較關鍵的配置頁麵
EXTRACT_ALL 表示輸出所有的函數，但是private和static函數不屬於其管製。
EXTRACT_PRIVATE 表示輸出private函數。
EXTRACT_STATIC 表示輸出static函數。同時還有幾個EXTRACT，相應查看文檔即可。
HIDE_UNDOC_MEMBERS 表示那些沒有使用doxygen格式描述的文檔（函數或類等）就不顯示了。當然，如果EXTRACT_ALL被啟用，那麽這個標誌其實是被忽略的。
INTERNAL_DOCS 主要指是否輸出注解中的@internal部分。如果沒有被啟動，那麽注解中所有的@internal部分都將在目標幫助中不可見。
CASE_SENSE_NAMES 是否關注大小寫名稱，注意，如果開啟了，那麽所有的名稱都將被小寫。對於C/C++這種字母相關的語言來說，建議永遠不要開啟。
HIDE_SCOPE_NAMES 域隱藏，建議永遠不要開啟。
SHOW_INCLUDE_FILES 是否顯示包含文件，如果開啟，幫助中會專門生成一個頁麵，裏麵包含所有包含文件的列表。
INLINE_INFO 如果開啟，那麽在幫助文檔中，inline函數前麵會有一個inline修飾詞來標明。
SORT_MEMBER_DOCS 如果開啟，那麽在幫助文檔列表顯示的時候，函數名稱會排序，否則按照解釋的順序顯示。
GENERATE_TODOLIST 是否生成TODOLIST頁麵，如果開啟，那麽包含在@todo注解中的內容將會單獨生成並顯示在一個頁麵中，其他的GENERATE選項同。
SHOW_USED_FILES 是否在函數或類等的幫助中，最下麵顯示函數或類的來源文件。
SHOW_FILES 是否顯示文件列表頁麵，如果開啟，那麽幫助中會存在一個一個文件列表索引頁麵。
Messages頁麵主要用來設置編譯時的輸出信息選項。編譯時的輸出信息，主要可以用來提醒一些輸入的錯誤語法。
QUIET 如果開啟，那麽表示關閉編譯時的輸出信息。
WARN_FORMAT 表示日誌輸出的格式，沒必要修改。
WARN_LOGFILE 表示信息是否輸出到LOG文件，因為有DoxyWizard的存在，所以這個選項沒有必要使用。
HTML頁麵
CHM_FILE 表示輸出的chm文件路徑
GENERATE_CHI 表示索引文件是否單獨輸出，建議關閉。否則每次生成兩個文件，比較麻煩。
TOC_EXPAND 表示是否在索引中列舉成員名稱以及分組（譬如函數，枚舉）名稱。
這個頁麵關係到生成chm的問題，不過很多選項很簡單，一看便知。
Preprocessor 頁麵是預處理頁麵，裏麵也有一些配置，但是個人感覺使用默認就行了。其他的幾個頁麵，基本上都要依賴於某些其他第三方的模塊，盡管有些doxygen自帶了，但是其詳細說明，還得考讀者自行研究。
同時附上常用的doxygen命令列表。注意doxygen的注解命令主要分成doxygen自建命令，HTML命令方式和XML命令方式。所有的命令都是以''或者'@'字符開頭，這表明如果你的注釋中有''開頭的單詞，你必須要修改成'\'。
由於doxygen命令比較多，另外就是doxygen的幫助文檔也是非常完善，所以，這裏僅僅列舉幾個常用的命令，其他命令請自行參考幫助文件。
@addtogroup 添加到一個組。
@brief 概要信息
@deprecated 已廢棄函數
@details 詳細描述
@note 開始一個段落，用來描述一些注意事項
@par 開始一個段落，段落名稱描述由你自己指定
@param 標記一個參數的意義
@code .. @endcode 包含一段代碼
@fn 函數說明
@ingroup 加入到一個組
@return 描述返回意義
@retval 描述返回值意義
@include 包含文件
問題：
如何編譯成CHM格式的幫助文件？
1. 你必須安裝微軟或其相兼容的chm編譯係統。通常為HTML Help Workshop。
2. 首先在[Wizard...]的Output頁麵中，選擇HTML，然後選擇到prepare for compressed HTML(.chm)。
3. 其次在[Expert...]的HTML頁麵中，將HHC_LOCATION指向微軟的hhc工具。通常為C:/Program Files/HTML Help Workshop/hhc.exe。然後點擊OK，保存，編譯即可。
如何像MSDN那樣在左邊的樹中顯示函數列表？
打開[Expert...]的HTML頁麵，然後選中TOC_EXPAND即可。
如何去掉CHM附帶的CHI文件？
注意在默認情況下，CHM會有一個CHI文件，似乎是用來加速索引的。我本人也遇到過很多用戶僅僅上傳了CHM，而沒有上傳CHI文件，導致無法正常顯示的情況。我不知道是否可以通過工具重建CHI文件，但是我覺得關閉這個功能即可。打開[Expert...]的HTML頁麵，取消 GENERATE_CHI即可。
如何像MSDN那樣右邊每頁顯示一個函數？
這個問題其實比較棘手，在[Expert...]中的Project頁麵，下麵有一個選項叫做SEPARATE_MEMBER_PAGES，把這個選項選中，這樣每個函數就是一個頁。但是會有一個問題，那就是右邊頁麵的旁邊多了所有函數的列表。很遺憾，經過研究，這個確實無法去掉。我的解決方法就是自己編譯一下doxygen，在memberlist.cpp的writeDocumentationPage函數中將 container->writeQuickMemberLinks(ol,md);連同附近幾行屏蔽掉即可。
如何在CHM中去掉當選擇SUBGROUPING後去掉分組的組信息？
這個功能就是在chm的左邊樹中直接列出函數列表，而不用點擊看右邊頁麵了。這個功能需要修改源代碼。在index.cpp中，屏蔽 writeGroupIndexItem函數的 Doxygen::indexList.addContentsItem，Doxygen::indexList.incContentsDepth和 Doxygen::indexList.decContentsDepth();即可，具體不解釋了，一看便知。
如何修改或者去掉右下腳Generated at ...的文字？
打開[Expert...]的HTML頁麵，然後在HTML_FOOTER中指定相應的HTML文件即可。注意HTML_FOOTER中至少包含BODY 和HTML結束標記。即一個最小的尾部HTML至少是這樣