doxygen注釋詳解-附有生成文檔的對照

1、Doxygen詳解目錄n使用Doxygen的目的.n安裝Doxygen所需工具.n配置DoxygennDoxygen注釋風(fēng)格使用Doxygen的目的n生成模塊文檔，方便以后維護(hù)模塊代碼。n提高代碼可讀性。n提高項(xiàng)目代碼的管理。n省略了自己寫readme文件（或文檔）。安裝Doxygen所需工具nDoxygen(版本:1.5.2)nGraphviz(版本: 2.12)niconv (GNU libiconv 1.9)nfr(版本: 2.1.1.120)nHTML Help Workshop (版本:4.74.8702.0)(注:這些工具放在 dataserver開發(fā)二部開發(fā)二部_公共盤白盒測試相

2、關(guān)生成文檔工具 )安裝Doxygen工具1.先解壓doxygen.rar;2.雙擊運(yùn)行 doxygen-1.5.2-setup.exe;3.安裝軟件提示語操作即可;4.把create_chm.bat、html_foot拷貝到Doxygen安裝目錄的bin文件夾里.5.把 Doxygen安裝目錄的bin路徑放在系統(tǒng)環(huán)境變量里; 6.Doxygen安裝完成;安裝Graphviz工具1.先解壓graphviz.rar；2.雙擊運(yùn)行g(shù)raphviz-2.12.exe；3.安裝軟件提示語操作即可；4. Graphviz安裝完成；安裝iconv、 fr工具1.先解壓iconv.rar和fr.rar；2.將

3、iconv.rar和fr.rar分別解壓出來的cygiconv-2.dll、cygintl-2.dll、cygwin1.dll、iconv.exe和fr.exe拷到“C:WINDOWSsystem32”；3.安裝完成；注注:上面安裝能夠運(yùn)行成功上面安裝能夠運(yùn)行成功,但是出現(xiàn)一個(gè)問題但是出現(xiàn)一個(gè)問題.就是我們編譯下載環(huán)境模塊時(shí)就是我們編譯下載環(huán)境模塊時(shí)iconviconv的的cygwin1.dllcygwin1.dll文件名明與文件名明與cygwincygwin的的cygwin1.dllcygwin1.dll文件名相同導(dǎo)致的文件名相同導(dǎo)致的. .所以編譯不通所以編譯不通過過. .解決方法解決方法

4、: :在下頁在下頁. . 安裝iconv、 fr工具解決方案新建一個(gè)系統(tǒng)變量名為新建一個(gè)系統(tǒng)變量名為”GBK”GBK”,這我固定了這我固定了.所以都以這個(gè)名字所以都以這個(gè)名字.這個(gè)就是要放置這個(gè)就是要放置iconviconv、 frfr工具里工具里文件的路徑文件的路徑.(.(這個(gè)路徑隨自己編寫這個(gè)路徑隨自己編寫) )、安裝HTML Help Workshop工具1.雙擊運(yùn)行 htmlhelp.exe;2.安裝軟件提示語操作即可;3. HTML Help Workshop安裝完成;注：注： HTML Help WorkshopHTML Help Workshop工具要安裝在這個(gè)路徑工具要安裝在這

5、個(gè)路徑“X:Program FilesHTML Help X:Program FilesHTML Help Workshop”Workshop”（X X：自己指定）：自己指定）. .附帶操作 為了方便運(yùn)行Doxygen工具與管理.為每個(gè)模塊創(chuàng)建一文件夾(如：“TEST”),在TEST文件夾里再創(chuàng)建src、doc文件夾。Src文件夾存放源文件，doc文件夾存放Doxygen輸出文件。順便把doxygenWD.bat和Doxygen配置文件“Doxyfile” 拷貝到doc文件夾下，如果要生成文檔就雙擊doxygenWD.bat即可。（模塊的目錄結(jié)構(gòu)如下 ）注注:Doxygen:Doxygen不支

6、持不支持中問路徑中問路徑, ,不要?jiǎng)?chuàng)建不要?jiǎng)?chuàng)建中文路徑中文路徑. .TEST |- src | | | |- test.c | |- test.h | |- doc | | | |- Doxyfile | |- doxygenWD.bat配置Doxygenn分為兩種: 向?qū)?Wizard)模式：將快速配置大多數(shù)重要設(shè)定,其他選項(xiàng)保持默認(rèn)值。 專家(Expert)模式：進(jìn)入全部的配置選項(xiàng)。向?qū)?Wizard)模式n向?qū)?Wizard)對話框-Project相關(guān)選項(xiàng)項(xiàng)目名稱，將作為于所生成項(xiàng)目名稱，將作為于所生成的程序文檔首頁標(biāo)題的程序文檔首頁標(biāo)題. .文檔版本號，可對應(yīng)于項(xiàng)目文檔版本號，可對應(yīng)于

7、項(xiàng)目版本號版本號 . .存放要生成項(xiàng)目文檔的項(xiàng)目存放要生成項(xiàng)目文檔的項(xiàng)目源文件路徑源文件路徑. .如果選上，就會(huì)連子文件夾的如果選上，就會(huì)連子文件夾的文件一起生成文當(dāng)。沒選，就文件一起生成文當(dāng)。沒選，就只會(huì)生成本文件夾的文件文檔只會(huì)生成本文件夾的文件文檔. .這里填入生成文檔文件輸出這里填入生成文檔文件輸出路徑路徑, ,這里只填文件夾名字就這里只填文件夾名字就可以了可以了. .為了大家工作方便為了大家工作方便, ,就規(guī)定統(tǒng)一寫就規(guī)定統(tǒng)一寫outputoutput文件夾文件夾向?qū)?Wizard)模式n向?qū)?Wizard)對話框-Mode相關(guān)選項(xiàng)選擇這個(gè)選擇這個(gè), ,只生成文檔實(shí)體只生成文檔實(shí)體,

8、 ,不不會(huì)生成源文件文檔會(huì)生成源文件文檔. .選擇這個(gè)選擇這個(gè),會(huì)生成全部實(shí)體會(huì)生成全部實(shí)體.因因此此,要選擇這個(gè)要選擇這個(gè).選擇這個(gè)選擇這個(gè), ,把源文件內(nèi)容導(dǎo)入把源文件內(nèi)容導(dǎo)入到項(xiàng)目文檔里到項(xiàng)目文檔里.(.(建議選擇建議選擇) )選擇項(xiàng)目文檔輸出格式選擇項(xiàng)目文檔輸出格式,測試測試C語言語言,就選擇個(gè)就選擇個(gè).向?qū)?Wizard)模式n向?qū)?Wizard)對話框-Output相關(guān)選項(xiàng)生成普通模式的生成普通模式的HTMLHTML生成文件列表格的生成文件列表格的HTMLHTML生成生成chmchm文件格式的文件格式的HTML,HTML,因此因此, ,就選這個(gè)就選這個(gè). .附帶查找功能附帶查找功能

9、, ,一般不選擇一般不選擇. .這項(xiàng)沒用到這項(xiàng)沒用到, ,因此把它選擇因此把它選擇取消取消. .這三項(xiàng)不要選擇這三項(xiàng)不要選擇向?qū)?Wizard)模式n向?qū)?Wizard)對話框-Diagrams相關(guān)選項(xiàng) 這兩個(gè)不選擇這兩個(gè)不選擇. .全選擇全選擇. .通過這個(gè)通過這個(gè)GraphVizGraphViz工具生成工具生成圖表圖表: :(1).(1).類的圖表類的圖表. .(2).(2).協(xié)作圖表協(xié)作圖表. .(3).(3).包含文件圖表包含文件圖表( (調(diào)用圖表調(diào)用圖表).).(4).(4).被包含文件圖表被包含文件圖表( (被調(diào)用圖表被調(diào)用圖表).).(5).(5).整個(gè)類層次結(jié)構(gòu)圖表整個(gè)類層次結(jié)

10、構(gòu)圖表. .(6).(6).調(diào)用圖表調(diào)用圖表( (函數(shù)函數(shù), ,文件文件).).專家(Expert)模式 由于經(jīng)過向?qū)?Wizard)模式快速的配置，所以專家(Expert)模式大部分也相應(yīng)配置好了。 那么，下面主要配置細(xì)節(jié)問題，其他就不詳細(xì)介紹都保持默認(rèn)選擇就可以。專家(Expert)模式n專家(Expert)對話框-Project相關(guān)選項(xiàng)DOXYFILE_ENCODINGDOXYFILE_ENCODING是是DoxyfileDoxyfile的的文本編碼。如果文件中有中文字符，文本編碼。如果文件中有中文字符，可以填寫可以填寫GBKGBK。把。把UTF-8UTF-8改為改為GBKGBK。輸出語

11、言相當(dāng)于程序資源，選擇輸出語言相當(dāng)于程序資源，選擇ChineseChinese。專家(Expert)模式n專家(Expert)對話框-Project相關(guān)選項(xiàng)取消選項(xiàng)取消選項(xiàng), ,不然會(huì)不然會(huì)顯示全路徑顯示全路徑: :如圖如圖1.1. 圖圖1 1專家(Expert)模式n專家(Expert)對話框-Messages相關(guān)選項(xiàng)將將WARN_LOGFILEWARN_LOGFILE填寫為填寫為error.txterror.txt。這樣，這樣，DoxygenDoxygen會(huì)將編譯時(shí)出現(xiàn)的警會(huì)將編譯時(shí)出現(xiàn)的警告和錯(cuò)誤保存在告和錯(cuò)誤保存在error.txterror.txt ，這樣，這樣可以對照修改?？梢詫φ?/p>

12、修改。 讓讓 doxygen doxygen 靜悄悄地為你生成文靜悄悄地為你生成文檔，只有出現(xiàn)警告或錯(cuò)誤時(shí)，才在檔，只有出現(xiàn)警告或錯(cuò)誤時(shí)，才在終端輸出提示信息終端輸出提示信息( (不選擇不選擇).).專家(Expert)模式n專家(Expert)對話框-Input相關(guān)選項(xiàng)指定輸入源文件目錄（指定輸入源文件目錄（INPUTINPUT）. .輸入文件編碼（輸入文件編碼（INPUT_ENCODINGINPUT_ENCODING）改）改為為GBK.GBK.對文件過濾選項(xiàng)對文件過濾選項(xiàng), ,我們這里只填我們這里只填* *.c .c * *.h.h.專家(Expert)模式n專家(Expert)對話框-M

13、essages相關(guān)選項(xiàng)可以通過參數(shù)可以通過參數(shù)HTML_HEADERHTML_HEADER和和HTML_FOOTERHTML_FOOTER定制頁面，參數(shù)值是包含定制內(nèi)容的文件定制頁面，參數(shù)值是包含定制內(nèi)容的文件名名. .這里我填了這里我填了html_foot html_foot 文件文件, ,內(nèi)可以打內(nèi)可以打開開html_foot html_foot 文件看文件看. . 這里只看效果圖這里只看效果圖: :如如圖圖2.2.選擇選擇GENERATE_HTMLHELPGENERATE_HTMLHELP后，后，DoxygenDoxygen會(huì)準(zhǔn)備生成會(huì)準(zhǔn)備生成chmchm文件需要的項(xiàng)目文件、文件需要的項(xiàng)

14、目文件、目錄文件和索引文件目錄文件和索引文件。 圖圖2 2專家(Expert)模式n專家(Expert)對話框-Dot相關(guān)選項(xiàng)可以選上可以選上UML_LOOKUML_LOOK、CALL_GRAPHCALL_GRAPH和和CALLER_GRAPHCALLER_GRAPH。CALL_GRAPHCALL_GRAPH是本函是本函數(shù)調(diào)用其它函數(shù)的示意圖數(shù)調(diào)用其它函數(shù)的示意圖. .效果如效果如: :圖圖3.3.圖3Doxygen注釋風(fēng)格 Doxygen指令目的為了生成更豐富與可讀性更強(qiáng)的文檔。所以總結(jié)5類常用的注釋風(fēng)格說明。 變量、宏定義、類型定義。 枚舉類型定義、結(jié)構(gòu)體類型定義類似。 函數(shù)定義。 模塊定

15、義（單獨(dú)顯示一頁 ）。 分組定義（在一頁內(nèi)分組顯示）。 變量、宏定義、類型定義簡要說明 變量、宏定義、類型定義注釋風(fēng)格類似。格式： /* 簡要說明文字 */ 變量（宏定義或類型定義）如： /* 簡要說明文字 */ #define FLOAT float /* brief 簡要說明文字（在前面加 brief 是標(biāo)準(zhǔn)格式） */ #define MIN_UINT 0 /* * 分行的簡要說明 n* 這是第二行的簡要說明*/int b; 注：不文檔化局部變量，只文檔化全局變量。注：不文檔化局部變量，只文檔化全局變量。/ /* * * * */ /這是固定格式，還要注意這是固定格式，還要注意/ /*

16、* *這這2 2個(gè)個(gè)“* * *”不能少也不能多。其他注釋風(fēng)不能少也不能多。其他注釋風(fēng)格也是這樣的。格也是這樣的?！皀n”作用是回車換行作用是回車換行. .“brief ”是注釋指令, “”也可以用”.枚舉類型定義、結(jié)構(gòu)體類型定義枚舉類型定義、結(jié)構(gòu)體類型定義注釋風(fēng)格類似。格式：/* 簡要說明文字 */typedef 類型 結(jié)構(gòu)體名字 成員1, /* 簡要說明文字 */ 成員2, /* 簡要說明文字 */ 成員3, /* 簡要說明文字 */結(jié)構(gòu)體別名； 注：所有的結(jié)構(gòu)體類型定義要放在枚舉類型定義前面。類型：類型：enum enum ，structstruct注意，要以 “” 小于號開頭 ，如過不

17、用“”，那這行的注釋就會(huì)被Doxygen認(rèn)為是成員2的注釋。函數(shù)定義指令格式: 執(zhí)行符指令操作符執(zhí)行符：或兩個(gè)。指令操作符：param、return、retval、note、 pre、 par、code、endcode、see、deprecated。（其實(shí)還有很多，這里的指令操作符已經(jīng)夠我們函數(shù)用了，所以不再列舉。）特殊符號指令符：-、#、:。（這三符號對于我們也夠用了）Param 指令操作符講解Param：指定函數(shù)參數(shù)指令操作符。Param 格式如下： param 參數(shù)名 參數(shù)說明 param in 參數(shù)名 參數(shù)說明 param out 參數(shù)名 參數(shù)說明例：/* *文件關(guān)閉函數(shù) * para

18、m file文件編號。 */ int CloseFile(int file);Doxygen生成效果return 指令操作符講解return：指定函數(shù)返回說明指令操作符。return格式如下： return 簡要說明例: /* * 寫入文件 * Param in file 文件編號 * Param in buffer 存放將要寫入的內(nèi)容 * Param in len寫入長度 * return 返回寫入的長度 * - -1 表示寫入失敗 */ int WriteFile(int file, const char* buffer, int len);retval指令操作符講解retval：指定函數(shù)

19、返回值說明指令操作符。(注:更前面的return有點(diǎn)不同.這里是返回值返回值說明)retval格式如下： retval 返回值 簡要說明 例: /* *文件關(guān)閉函數(shù) * param file文件編號。 * retval 0 表示成功* retval -1 表示失敗 */ int CloseFile(int file);note 指令操作符講解note：指定函數(shù)注意項(xiàng)事或重要的注解指令操作符。note格式如下： note 簡要說明例: /* *打開文件函數(shù) *Param in name 文件名 *Param in “rb” 打開模式 *return 返回文件編號 *- -1表示打開文件失敗 *n

20、ote 文件打開成功后,必須使用 CloseFile 函數(shù)關(guān)閉 */ int OpenFile(U8* file_name, U8* file_mode);pre 指令操作符講解pre：指定函數(shù)前置條件指令操作符pre格式如下： pre 簡要說明例: /* *文件關(guān)閉函數(shù) * param file文件編號。 * retval 0 表示成功* retval -1 表示失敗 * pre file 變量必須使用OpenFile 返回值 */ int CloseFile(int file);par指令操作符講解par：指定擴(kuò)展性說明指令操作符講。（它一般跟code、endcode一起使用 ）par格式

21、如下： par 擴(kuò)展名字例: /* * 打開文件函數(shù) * Param in name 文件名 * Param in “rb” 打開模式 * return 返回文件編號 * - -1表示打開文件失敗 * par 示例: * code /用文本只讀方式打開文 int f = OpenFile(”c:test.txt”, “rb”); * endcode */ int OpenFile(U8* file_name, U8* file_mode);code、endcode指令操作符講解code、endcode：指定code、endcode格式如下： code 簡要說明(內(nèi)容) endcode例: /*

22、 * 打開文件函數(shù) * Param in name 文件名 * Param in “rb” 打開模式 * return 返回文件編號 * - -1表示打開文件失敗 * par 示例: * code /用文本只讀方式打開文 int f = OpenFile(”c:test.txt”, “rb”); * endcode */ int OpenFile(U8* file_name, U8* file_mode);see指令操作符講解see：指定參考信息。see格式如下： see 簡要參考內(nèi)容例: /* *文件關(guān)閉函數(shù) * param file文件編號。 * retval 0 表示成功* retval -1 表示失敗 * pre file 變量必須使用OpenFile 返回值 * see 函數(shù):OpenFile */ int CloseFile(int file);“:”是指定有