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

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

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

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

4、ygen配置文件在stepl中，有個(gè)最重要的設(shè)置就是在Wizard.的Project頁(yè)面中的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)提到過(guò)， DoxyWizard和doxygen是兩個(gè)不同的進(jìn)程，所以在DoxyWi

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

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

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

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

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

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

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

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

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

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

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

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í)候只需要用記事本打開(kāi)doxyfile配置文件， 輸入相應(yīng)中文即可。注意保存的時(shí)候保存成ANSI編碼即可。保存成其他格式的話可能需要 去掉BOM，比較麻煩，沒(méi)

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

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