幾年前看過幾個(gè)開源項(xiàng)目的文檔發(fā)現(xiàn)每個(gè)開源都會有一

1、幾年前，看過幾個(gè)開源項(xiàng)目的文檔，發(fā)現(xiàn)每個(gè)開源都會有一個(gè)幫助文件，感覺注釋非常詳細(xì)。 當(dāng)時(shí)就感慨開源項(xiàng)目的人精力充沛。后發(fā)覺注釋和代碼有很多相似之處，經(jīng)過研究，了解到 了 doxygen。正巧前段時(shí)間公司要程序生成文檔，以前很多都是都是手工完成的。經(jīng)過交 流，我們修改了部分源代碼的注釋，同時(shí)我寫一個(gè)幫助，放到這里。doxygen是一款源代碼幫助文檔生成工具。依靠源代碼中的注釋，doxygen可以輕 松的生成多種格式的幫助文檔，供開發(fā)者閱讀。doxygen的使用方法很簡單：第一步，需要修改源代碼文件，規(guī)范現(xiàn)有注釋。為了使注釋輕松智能的變成可讀的文 檔。doxygen規(guī)定了自己的注釋格式，這樣太才可

2、以解析。最常用的注釋格式是：/*there is comment.I*/或/*!there is comment.*/同時(shí)，為了區(qū)分注釋的用途，doxygen定義了很多關(guān)鍵字，用來標(biāo)識注釋描述的代 碼段或者用途。常用后面跟用途關(guān)鍵字來標(biāo)識，關(guān)鍵字在doxygen附帶的幫助文件中有 很詳細(xì)的解析(在Special Commands這一節(jié)中)，這里就不在累贅了。這里有一個(gè)地方需 要注意一下，描述的各個(gè)分段之間最好用tab空開，用空格有的時(shí)候會出現(xiàn)問題。如：/*brief這是一個(gè)函數(shù)param a 參數(shù)一param b 參數(shù)二return 無返回值*/void fooFun(int a, int b

3、);第二步，建立doxygen配置文件。doxygen執(zhí)行的時(shí)候需要一個(gè)配置文件，即每生 成一個(gè)chm都會有一個(gè)配置文件來進(jìn)行生成工程具體信息的描述。手工編寫那個(gè)配置文件 比較繁瑣，還好doxygen隨身附帶了一個(gè)DoxyWizard，利用這個(gè)向?qū)?。你可以方便的?置想要的信息。注意DoxyWizard僅僅是一個(gè)界面，他最終編譯的時(shí)候還是執(zhí)行了 doxygen.exe，傳輸時(shí)不要只拷貝這一個(gè)文件。打開DoxyWizard，會發(fā)現(xiàn)DoxyWizard分成了三個(gè)區(qū)域。在step1中有三個(gè)按鈕。按鈕Wizard.里面配置項(xiàng)目的一些基本信息按鈕Expert.包含高級配置信息按鈕Load.加載一個(gè)dox

4、ygen配置文件在stepl中，有個(gè)最重要的設(shè)置就是在Wizard.的Project頁面中的Source code directory選項(xiàng)。把這個(gè)指向你的源代碼文件路徑。Scan recursively表示是否遞歸遍歷。step1完成之后，你必須要保存一下doxygen配置文件。只需要點(diǎn)擊step2的保存 按鈕即可。step3中的工作目錄，也就是doxygen最終生成的幫助文檔(chm)的存放路徑。最后，點(diǎn)擊step4中的Start按鈕即可。在Output列表中。是doxygen生成編譯時(shí)生成的信息。注意上面已經(jīng)提到過， DoxyWizard和doxygen是兩個(gè)不同的進(jìn)程，所以在DoxyWi

5、zard輸出日志的時(shí)候可能 會有停頓。具體顯示時(shí)候的通信機(jī)制我沒有看，但這和機(jī)器或者doxygen本身的代碼沒有 關(guān)系。我在這里主要講一些基本常用的屬性，很多我覺得意義不大的，請自行研究，這里就 不過多解釋了。在Wizard.中沒有特別復(fù)雜的地方，稍微看一眼便知。在Expert.按鈕中，有一個(gè)tab頁，下面來逐一解釋：Project頁面，主要包括項(xiàng)目的基本配置。TAB_SIZE主要是幫助文件中代碼的縮進(jìn)尺寸，譬如code和endcode段 中代碼的排版，建議符合習(xí)慣，設(shè)置成4。OPTIMIZE_OUTPUT_FOR_C這個(gè)選項(xiàng)選擇后，生成文檔的一些描述性名 稱會發(fā)生變化，主要是符合C習(xí)慣。如果

6、是純C代碼，建議選擇。SUBGROUPING這個(gè)選項(xiàng)選擇后，輸出將會按類型分組。Build頁面，這個(gè)頁面是生成幫助信息中比較關(guān)鍵的配置頁面EXTRACT_ALL表示輸出所有的函數(shù)，但是private和static函數(shù)不屬于其管 制。EXTRACT_PRIVATE 表示輸出 private 函數(shù)。EXTRACT_STATIC表示輸出static函數(shù)。同時(shí)還有幾個(gè)EXTRACT，相應(yīng)查 看文檔即可。HIDE_UNDOC_MEMBERS表示那些沒有使用doxygen格式描述的文檔(函數(shù)或類等)就不顯示了。當(dāng)然，如果EXTRACT_ALL被啟用，那么這個(gè)標(biāo)志其實(shí)是被 忽略的。INTERNAL_DOCS

7、主要指是否輸出注解中的internal部分。如果沒有被啟 動，那么注解中所有的internal部分都將在目標(biāo)幫助中不可見。CASE_SENSE_NAMES是否關(guān)注大小寫名稱，注意，如果開啟了，那么所有 的名稱都將被小寫。對于C/C+這種字母相關(guān)的語言來說，建議永遠(yuǎn)不要開啟。HIDE_SCOPE_NAMES域隱藏，建議永遠(yuǎn)不要開啟。SHOW_INCLUDE_FILES是否顯示包含文件，如果開啟，幫助中會專門生 成一個(gè)頁面，里面包含所有包含文件的列表。INLINE_INFO如果開啟，那么在幫助文檔中，inline函數(shù)前面會有一個(gè)inline 修飾詞來標(biāo)明。SORT_MEMBER_DOCS如果開啟，

8、那么在幫助文檔列表顯示的時(shí)候，函數(shù) 名稱會排序，否則按照解釋的順序顯示。GENERATE_TODOLIST是否生成TODOLIST頁面，如果開啟，那么包含 在todo注解中的內(nèi)容將會單獨(dú)生成并顯示在一個(gè)頁面中，其他的GENERATE選項(xiàng)同。SHOW_USED_FILES是否在函數(shù)或類等的幫助中，最下面顯示函數(shù)或類的 來源文件。SHOW_FILES是否顯示文件列表頁面，如果開啟，那么幫助中會存在一個(gè)一 個(gè)文件列表索引頁面。Messages頁面主要用來設(shè)置編譯時(shí)的輸出信息選項(xiàng)。編譯時(shí)的輸出信息，主要可 以用來提醒一些輸入的錯(cuò)誤語法。QUIET如果開啟，那么表示關(guān)閉編譯時(shí)的輸出信息。WARN_FOR

9、MAT表示日志輸出的格式，沒必要修改。WARN_LOGFILE表示信息是否輸出到LOG文件，因?yàn)橛蠨oxyWizard的 存在，所以這個(gè)選項(xiàng)沒有必要使用。HTML頁面CHM_FILE表示輸出的chm文件路徑GENERATE_CHI表示索引文件是否單獨(dú)輸出，建議關(guān)閉。否則每次生成兩個(gè) 文件，比較麻煩。TOC_EXPAND表示是否在索引中列舉成員名稱以及分組（譬如函數(shù)，枚舉） 名稱。這個(gè)頁面關(guān)系到生成chm的問題，不過很多選項(xiàng)很簡單，一看便知。Preprocessor頁面是預(yù)處理頁面，里面也有一些配置，但是個(gè)人感覺使用默認(rèn)就 行了。其他的幾個(gè)頁面，基本上都要依賴于某些其他第三方的模塊，盡管有些do

10、xygen自 帶了，但是其詳細(xì)說明，還得考讀者自行研究。同時(shí)附上常用的doxygen命令列表。注意doxygen的注解命令主要分成doxygen 自建命令，HTML命令方式和XML命令方式。所有的命令都是以或者字符開頭，這 表明如果你的注釋中有開頭的單詞，你必須要修改成。由于doxygen命令比較多，另外就是doxygen的幫助文檔也是非常完善，所以， 這里僅僅列舉幾個(gè)常用的命令，其他命令請自行參考幫助文件。addtogroup添加到一個(gè)組。brief概要信息deprecated巳廢棄函數(shù)details詳細(xì)描述note開始一個(gè)段落，用來描述一些注意事項(xiàng)par開始一個(gè)段落，段落名稱描述由你自己指

11、定param標(biāo)記一個(gè)參數(shù)的意義code . endcode 包含一段代碼fn函數(shù)說明ingroup加入到一個(gè)組return描述返回意義retval描述返回值意義include包含文件問題：如何編譯成CHM格式的幫助文件？你必須安裝微軟或其相兼容的chm編譯系統(tǒng)。通常為HTML Help Workshop。首先在Wizard.的Output頁面中，選擇HTML，然后選擇到prepare for compressed HTML(.chm)。其次在Expert.的HTML頁面中，將HHC_LOCATION指向微軟的hhc工具。 通常為 C:/Program Files/HTML Help Works

12、hop/hhc.exe 然后點(diǎn)擊 OK，保存，編譯 即可。如何像MSDN那樣在左邊的樹中顯示函數(shù)列表？打開Expert.的HTML頁面，然后選中TOC_EXPAND即可。如何去掉CHM附帶的CHI文件？注意在默認(rèn)情況下，CHM會有一個(gè)CHI文件，似乎是用來加速索引的。我本人也遇 到過很多用戶僅僅上傳了 CHM，而沒有上傳CHI文件，導(dǎo)致無法正常顯示的情況。我不知 道是否可以通過工具重建CHI文件，但是我覺得關(guān)閉這個(gè)功能即可。打開Expert.的 HTML頁面，取消GENERATE_CHI即可。如何像MSDN那樣右邊每頁顯示一個(gè)函數(shù)？這個(gè)問題其實(shí)比較棘手，在Expert.中的Project頁面，

13、下面有一個(gè)選項(xiàng)叫做 SEPARATE_MEMBER_PAGES，把這個(gè)選項(xiàng)選中，這樣每個(gè)函數(shù)就是一個(gè)頁。但是會有 一個(gè)問題，那就是右邊頁面的旁邊多了所有函數(shù)的列表。很遺憾，經(jīng)過研究，這個(gè)確實(shí)無法 去掉。我的解決方法就是自己編譯一下doxygen，在memberlist.cpp的 writeDocumentationPage 函數(shù)中將 container-writeQuickMemberLinks(ol,md); 連同附近幾行屏蔽掉即可。如何在CHM中去掉當(dāng)選擇SUBGROUPING后去掉分組的組信息？這個(gè)功能就是在chm的左邊樹中直接列出函數(shù)列表，而不用點(diǎn)擊看右邊頁面了。這 個(gè)功能需要修改源代

14、碼。在index.cpp中，屏蔽writeGroupIndexItem函數(shù)的Doxygen:indexList.addContentsItem, Doxygen:indexList.incContentsDepth 和 Doxygen:indexList.decContentsDepth();即可，具體不解釋了，一看便知。如何修改或者去掉右下腳Generated at .的文字？打開Expert.的HTML頁面，然后在HTML_FOOTER中指定相應(yīng)的HTML文件 即可。注意HTML_FOOTER中至少包含BODY和HTML結(jié)束標(biāo)記。即一個(gè)最小的尾部 HTML至少是這樣。同理，如果你要指定了

15、HTML_HEADER，他至 少包含 如何生成組？組就是可以把同類的函數(shù)放到一個(gè)根下的顯示方式o doxygen支持grouping，即你 可以把相關(guān)的代碼通過標(biāo)志，放到同一個(gè)組中，便于查看。這主要是通過幾個(gè)內(nèi)置語法命令。 首先通過defgroup定義一個(gè)組，然后要把分組的函數(shù)或者類等，通過標(biāo)志ingroup加 入相應(yīng)的組。這樣，相應(yīng)的函數(shù)就被放置在同一個(gè)組中。如何生成中文幫助？點(diǎn)擊Expert.，在頁 Project 的 OUTPUT_LANGUAGE，選擇Chinese，這樣輸 出的幫助提示信息就是中文。具體中文提示信息的文字在源代碼中。如何徹底解決DoxyGen的輸出中文chm的亂碼問題

16、？DoxyGen的實(shí)現(xiàn)中大概有三處編碼的設(shè)置。首先是，doxyfile，也就是配置文件。 其次，INPUT_ENCODING，也就是DoxyGen需要解析的輸入文件的編碼。最后，就是 輸出的編碼。譬如CHM左邊的索引編碼。首先是chm的標(biāo)題亂碼，這個(gè)比較好解決，因?yàn)镈oxyWizard使用QT做的界面， 它內(nèi)部做了轉(zhuǎn)換，所以在DoxyWizard中輸入中文，在保存的時(shí)候，他自己做了轉(zhuǎn)碼，導(dǎo) 致doxyfile中的最終的保存信息不正確。這個(gè)時(shí)候只需要用記事本打開doxyfile配置文件， 輸入相應(yīng)中文即可。注意保存的時(shí)候保存成ANSI編碼即可。保存成其他格式的話可能需要 去掉BOM，比較麻煩，沒

17、研究了。這個(gè)相應(yīng)的編碼設(shè)置在Expert.中，頁P(yáng)roject的 DOXYFILE_ENCODING，不輸入或者默認(rèn)為UTF-8都行。其次是右邊內(nèi)容亂碼，這個(gè)多半是因?yàn)槟銢]有配置好輸入的文件編碼類型造成的。在 Expert.的Input頁面中，有一個(gè)INPUT_ENCODING，這個(gè)選項(xiàng)表示輸入文件的編 碼方式，這要和你處理的源文件格式一致。對于我們來說(使用vs的人)，一般設(shè)置為 GB2312o當(dāng)然，再次聲明，編碼方式取決于源文件的編碼方式。如果文件編碼已經(jīng)是UTF-8 了，然而你還將其設(shè)置成GB2312,那么DoxyGen會將UTF-8當(dāng)成ANSI再進(jìn)行一次 UTF-8轉(zhuǎn)換，自然會出錯(cuò)了。

18、最后也是經(jīng)常遇到的問題就是DoxyGen生成的CHM文件的左邊樹目錄的中文變 成了亂碼。這個(gè)只需要將chm索引的編碼類型修改為GB2312即可。在HTML的 CHM_INDEX_ENCODING中輸入GB2312即可。然而這種方法下，還有一個(gè)瑕疵之處， 就是chm的搜索頁的搜索結(jié)果中顯示的中文文字卻變成亂碼了。這是因?yàn)镈oxyGen默認(rèn) 開啟了 HTML Help Workshop的Full-text search全文搜索選項(xiàng)，他在進(jìn)行全文搜索的 時(shí)候，應(yīng)該是打開文件然后按照ANSI進(jìn)行搜索的，（資料表示HHW不支持UTF-8，僅 支持ISO-8859-1或者windows-1252編碼。）而Doxygen生成的右邊界面統(tǒng)一是 UTF-8，這自然出現(xiàn)了問題。而在這種情況下做全文搜索，理論上只能搜索英文。無奈，我們的解決方案只能是重新編譯DoxyGen代碼，為了滿足搜索，只要保證右 邊的頁面文件不是UTF-8即可。我們首先修改writeDefaultHeaderFile這個(gè)函數(shù)的 代碼，將其charset=GB2312。然后在TranslatorDecoder的構(gòu)造函數(shù)中修改 m_toUtf8 = （void*）-1卿屏蔽文本寫入時(shí)最終的轉(zhuǎn)換函數(shù)。最后刪除 INPUT_ENCODING的設(shè)置或者輸入U(xiǎn)TF-8。這樣會