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

Doxygen詳解目錄,使用Doxygen的目的.安裝Doxygen所需工具.配置DoxygenDoxygen注釋風格,使用Doxygen的目的,生成模塊文檔，方便以后維護模塊代碼。提高代碼可讀性。提高項目代碼的管理。省略了自己寫readme文件（或文檔）。,安裝Doxygen所需工具,Doxygen(版本:1.5.2)Graphviz(版本:2.12)iconv(GNUlibiconv1.9)fr(版本:2.1.1.120)HTMLHelpWorkshop(版本:4.74.8702.0)(注:這些工具放在dataserver開發(fā)二部開發(fā)二部_公共盤白盒測試相關生成文檔工具),安裝Doxygen工具,1.先解壓doxygen.rar;2.雙擊運行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.雙擊運行graphviz-2.12.exe；3.安裝軟件提示語操作即可；4.Graphviz安裝完成；,安裝iconv、fr工具,1.先解壓iconv.rar和fr.rar；2.將iconv.rar和fr.rar分別解壓出來的cygiconv-2.dll、cygintl-2.dll、cygwin1.dll、iconv.exe和fr.exe拷到“C:WINDOWSsystem32”；3.安裝完成；注:上面安裝能夠運行成功,但是出現(xiàn)一個問題.就是我們編譯下載環(huán)境模塊時iconv的cygwin1.dll文件名明與cygwin的cygwin1.dll文件名相同導致的.所以編譯不通過.解決方法:在下頁.,安裝iconv、fr工具解決方案,新建一個系統(tǒng)變量名為”GBK”,這我固定了.所以都以這個名字.,這個就是要放置iconv、fr工具里文件的路徑.(這個路徑隨自己編寫),、,安裝HTMLHelpWorkshop工具,1.雙擊運行htmlhelp.exe;2.安裝軟件提示語操作即可;3.HTMLHelpWorkshop安裝完成;注：HTMLHelpWorkshop工具要安裝在這個路徑“X:ProgramFilesHTMLHelpWorkshop”（X：自己指定）.,附帶操作,為了方便運行Doxygen工具與管理.為每個模塊創(chuàng)建一文件夾(如：“TEST”),在TEST文件夾里再創(chuàng)建src、doc文件夾。Src文件夾存放源文件，doc文件夾存放Doxygen輸出文件。順便把doxygenWD.bat和Doxygen配置文件“Doxyfile”拷貝到doc文件夾下，如果要生成文檔就雙擊doxygenWD.bat即可。（模塊的目錄結構如下）注:Doxygen不支持中問路徑,不要創(chuàng)建中文路徑.,TEST|-src|-test.c|-test.h|-doc|-Doxyfile|-doxygenWD.bat,配置Doxygen,分為兩種:向導(Wizard)模式：將快速配置大多數(shù)重要設定,其他選項保持默認值。專家(Expert)模式：進入全部的配置選項。,向導(Wizard)模式,向導(Wizard)對話框-Project相關選項,項目名稱，將作為于所生成的程序文檔首頁標題.,文檔版本號，可對應于項目版本號.,存放要生成項目文檔的項目源文件路徑.,這里填入生成文檔文件輸出路徑,這里只填文件夾名字就可以了.為了大家工作方便,就規(guī)定統(tǒng)一寫output文件夾,向導(Wizard)模式,向導(Wizard)對話框-Mode相關選項,選擇這個,只生成文檔實體,不會生成源文件文檔.,選擇這個,會生成全部實體.因此,要選擇這個.,選擇這個,把源文件內容導入到項目文檔里.(建議選擇),選擇項目文檔輸出格式,測試C語言,就選擇個.,向導(Wizard)模式,向導(Wizard)對話框-Output相關選項,生成普通模式的HTML,生成文件列表格的HTML,生成chm文件格式的HTML,因此,就選這個.,附帶查找功能,一般不選擇.,這項沒用到,因此把它選擇取消.,這三項不要選擇,向導(Wizard)模式,向導(Wizard)對話框-Diagrams相關選項,這兩個不選擇.,全選擇.通過這個GraphViz工具生成圖表:(1).類的圖表.(2).協(xié)作圖表.(3).包含文件圖表(調用圖表).(4).被包含文件圖表(被調用圖表).(5).整個類層次結構圖表.(6).調用圖表(函數(shù),文件).,專家(Expert)模式,由于經(jīng)過向導(Wizard)模式快速的配置，所以專家(Expert)模式大部分也相應配置好了。那么，下面主要配置細節(jié)問題，其他就不詳細介紹都保持默認選擇就可以。,專家(Expert)模式,專家(Expert)對話框-Project相關選項,DOXYFILE_ENCODING是Doxyfile的文本編碼。如果文件中有中文字符，可以填寫GBK。把UTF-8改為GBK。,輸出語言相當于程序資源，選擇Chinese。,專家(Expert)模式,專家(Expert)對話框-Project相關選項,取消選項,不然會顯示全路徑:如圖1.,圖1,專家(Expert)模式,專家(Expert)對話框-Messages相關選項,將WARN_LOGFILE填寫為error.txt。這樣，Doxygen會將編譯時出現(xiàn)的警告和錯誤保存在error.txt，這樣可以對照修改。,讓doxygen靜悄悄地為你生成文檔，只有出現(xiàn)警告或錯誤時，才在終端輸出提示信息(不選擇).,專家(Expert)模式,專家(Expert)對話框-Input相關選項,指定輸入源文件目錄（INPUT）.,輸入文件編碼（INPUT_ENCODING）改為GBK.,對文件過濾選項,我們這里只填*.c*.h.,專家(Expert)模式,專家(Expert)對話框-Messages相關選項,可以通過參數(shù)HTML_HEADER和HTML_FOOTER定制頁面，參數(shù)值是包含定制內容的文件名.這里我填了html_foot文件,內可以打開html_foot文件看.這里只看效果圖:如圖2.,選擇GENERATE_HTMLHELP后，Doxygen會準備生成chm文件需要的項目文件、目錄文件和索引文件。,圖2,專家(Expert)模式,專家(Expert)對話框-Dot相關選項,可以選上UML_LOOK、CALL_GRAPH和CALLER_GRAPH。CALL_GRAPH是本函數(shù)調用其它函數(shù)的示意圖.效果如:圖3.,圖3,Doxygen注釋風格,Doxygen指令目的為了生成更豐富與可讀性更強的文檔。所以總結5類常用的注釋風格說明。變量、宏定義、類型定義。枚舉類型定義、結構體類型定義類似。函數(shù)定義。模塊定義（單獨顯示一頁）。分組定義（在一頁內分組顯示）。,變量、宏定義、類型定義簡要說明,變量、宏定義、類型定義注釋風格類似。格式：/*簡要說明文字*/變量（宏定義或類型定義）如：/*簡要說明文字*/#defineFLOATfloat/*brief簡要說明文字（在前面加brief是標準格式）*/#defineMIN_UINT0/*分行的簡要說明n*這是第二行的簡要說明*/intb;注：不文檔化局部變量，只文檔化全局變量。,/*/這是固定格式，還要注意/*這2個“*”不能少也不能多。其他注釋風格也是這樣的。,“n”作用是回車換行.,“brief”是注釋指令,“”也可以用”.,枚舉類型定義、結構體類型定義,枚舉類型定義、結構體類型定義注釋風格類似。格式：/*簡要說明文字*/typedef類型結構體名字成員1,/*簡要說明文字*/成員2,/*簡要說明文字*/成員3,/*簡要說明文字*/結構體別名；注：所有的結構體類型定義要放在枚舉類型定義前面。,類型：enum，struct,注意，要以“”小于號開頭，如過不用“”，那這行的注釋就會被Doxygen認為是成員2的注釋。,函數(shù)定義,指令格式:執(zhí)行符指令操作符執(zhí)行符：或兩個。指令操作符：param、return、retval、note、pre、par、code、endcode、see、deprecated。（其實還有很多，這里的指令操作符已經(jīng)夠我們函數(shù)用了，所以不再列舉。）特殊符號指令符：-、#、:。（這三符號對于我們也夠用了）,Param指令操作符講解,Param：指定函數(shù)參數(shù)指令操作符。Param格式如下：param參數(shù)名參數(shù)說明paramin參數(shù)名參數(shù)說明paramout參數(shù)名參數(shù)說明例：/*文件關閉函數(shù)*paramfile文件編號。*/intCloseFile(intfile);,Doxygen生成效果,return指令操作符講解,return：指定函數(shù)返回說明指令操作符。return格式如下：return簡要說明例:/*寫入文件*Paraminfile文件編號*Paraminbuffer存放將要寫入的內容*Paraminlen寫入長度*return返回寫入的長度*-1表示寫入失敗*/intWriteFile(intfile,constchar*buffer,intlen);,retval指令操作符講解,retval：指定函數(shù)返回值說明指令操作符。(注:更前面的return有點不同.這里是返回值說明)retval格式如下：retval返回值簡要說明例:/*文件關閉函數(shù)*paramfile文件編號。*retval0表示成功*retval-1表示失敗*/intCloseFile(intfile);,note指令操作符講解,note：指定函數(shù)注意項事或重要的注解指令操作符。note格式如下：note簡要說明例:/*打開文件函數(shù)*Paraminname文件名*Paramin“rb”打開模式*return返回文件編號*-1表示打開文件失敗*note文件打開成功后,必須使用CloseFile函數(shù)關閉*/intOpenFile(U8*file_name,U8*file_mode);,pre指令操作符講解,pre：指定函數(shù)前置條件指令操作符pre格式如下：pre簡要說明例:/*文件關閉函數(shù)*paramfile文件編號。*retval0表示成功*retval-1表示失敗*prefile變量必須使用OpenFile返回值*/intCloseFile(intfile);,par指令操作符講解,par：指定擴展性說明指令操作符講。（它一般跟code、endcode一起使用）par格式如下：par擴展名字例:/*打開文件函數(shù)*Paraminname文件名*Paramin“rb”打開模式*return返回文件編號*-1表示打開文件失敗*par示例:*code/用文本只讀方式打開文intf=OpenFile(”c:test.txt”,“rb”);*endcode*/intOpenFile(U8*file_name,U8*file_mode);,code、endcode指令操作符講解,code、endcode：指定code、endcode格式如下：code簡要說明(內容)endcode例:/*打開文件函數(shù)*Paraminname文件名*Paramin“rb”打開模式*return返回文件編號*-1表示打開文件失敗*par示例:*code/用文本只讀方式打開文intf=OpenFile(”c:test.txt”,“rb”);*endcode*/intOpenFile(U8*file_name,U8*file_mode);,see指令操作符講解,see：指定參考信息。see格式如下：see簡要參考內容例:/*文件關閉函數(shù)*paramfile文件編號。*retval0表示成功*retval-1表示失敗*prefile變量必須使用OpenFile返回值*see函數(shù):OpenFile*/intCloseFile(intfile);,“:”是指定有連接功能.可以看文檔里的OpenFile變成綠.點擊它可以跳轉到OpenFile.,deprecated指令操作符講解,deprecated：指定函數(shù)過時指令操作符。deprecated格式如下：deprecated簡要說明例:/*文件關閉函數(shù)*paramfile文件編號。*retval0表示成功*retval-1表示失敗*deprecated由于特殊的原因,將來的版本中取消。*/intCloseFile(intfile);,-、#、:指令操作符講解,-：生成一個黑心圓.-#：指定按順序標記。:：指定連接函數(shù)功能。（注：空格和“:”有連接功能,但建議還是使用”:”。只對函數(shù)有用。）它們格式如下:(-和:例子前面有了,就介紹-#例子。)-簡要說明-#簡要說明:函數(shù)名例：/*paraminp只能輸入以下參數(shù)：*-#a:代表一功能*-#b:代表二功能*-#c:代表