Doxygen代碼注釋規(guī)范

1、基于Doxygen的代碼注釋規(guī)范一、Doxygen系列軟件介紹1、DoxygenDoxygen是一種開源跨平臺的，以類似JavaDoc風(fēng)格描述的文檔系統(tǒng)，完全支持C、C+十Java、Objective-C和IDL語言， 部分支持PHRC拄注釋的語法與Qt-Doc、KDocOJavaDoc兼容。Doxgen可以從一套歸檔源文件開始，生成HTML格式的在線類瀏覽器，或離線的LATEXRTF參考手冊。Doxygen能將程序中的特定批注轉(zhuǎn)換成為說明文件。它可以依據(jù)程序本身的結(jié)構(gòu)，將程序中按規(guī)范注釋的批注經(jīng)過處理生成一個(gè)純粹的參考手冊，通過提取代碼結(jié)構(gòu)或借助自動(dòng)生成的包含依賴圖(includedepen

2、dencygraphs)、繼承圖(inheritancediagram)以及協(xié)作圖(collaborationdiagram)來可視化文檔之間的關(guān)系，Doxygen生成的幫助文檔的格式可以是CHMRTFPostScript、PDFHTM野。2、graphvizGraphviz(GraphVisualizationSoftware)是一個(gè)由AT&T實(shí)驗(yàn)室啟動(dòng)的開源工具包，用于繪制DOTS言腳本描述的圖形。要使用Doxygen生成依賴圖、繼承圖以及協(xié)作圖，必須先安裝graphviz軟件。3、HTMLHelpWorkshop微軟出品的HTMLHelpWorkshop是制作CHMfc件的最佳工

3、具，它能將HTML文件編譯生成CHMJ：檔。Doxygen軟件默認(rèn)生成HTMLC件或Latex文件，我們要通過HTM民成CHM文檔，需要先安裝HTMLHelpWorkshop軟件，并在Doxygen中進(jìn)行關(guān)聯(lián)。二、軟件下載與安裝Doxygen下載(doxygen-187-setup.exe):http:/www.stack.nl/-dimitri/doxygen/download.htmlgraphviz(forwindows)下載：/Download.phpHTMLHelpWorkshop(1.32)下載：http:/ 使Doxygenhtml文件

4、夾中找到index.chm文件即為輸入代碼的文檔說明(10)Run-RunDoxygen即可運(yùn)行Doxygen,運(yùn)行完成后在輸出目錄中的把它識別出來，并將它組織到生成的文檔中去。在每個(gè)代碼項(xiàng)中都可以有兩類描述：一種就是brief描述，另一種就是detailed。兩種都是可選的，但不能同時(shí)沒有。簡述(brief)就是在一行內(nèi)簡述地描述。而詳細(xì)描述(detailed)則提供更長，更詳細(xì)的文檔。在Doxygen中， 主要通過以下方法將注釋塊標(biāo)識成詳細(xì)(detailed)描述：JavaDoc風(fēng)格，在C風(fēng)格注釋塊開始使用兩個(gè)星號*:/*.描述*/Qt風(fēng)格代碼注釋，即在C風(fēng)格注釋塊開始處添加一個(gè)嘆號!：/

5、*!*.描述*/使用連續(xù)兩個(gè)以上C+注釋行所組成的注釋塊，而每個(gè)注釋行開始處要多寫一個(gè)斜杠或?qū)懸粋€(gè)嘆號：/.描述/同樣的，簡要說明(brief)有也有多種方式標(biāo)識，這里推薦使用brief命令強(qiáng)制說明，例如：/* brief簡要注釋BriefDescription.*/或者/brief簡要注釋BriefDescription.Ill(1)Doxygen并不處理所有的注釋，doxygen重點(diǎn)關(guān)注與程序結(jié)構(gòu)有關(guān)的注釋， 比如：文件、類、結(jié)構(gòu)、函數(shù)、全局變量、宏等注釋，而忽略函數(shù)內(nèi)局部變量、代碼等的注釋。(2)注釋應(yīng)寫在對應(yīng)的函數(shù)或變量前面。JavaDoc風(fēng)格下，自動(dòng)會(huì)把第一個(gè)句號”.前的文本作為簡要

6、注釋，后面的為詳細(xì)注釋。你也可以用空行把簡要注釋和詳細(xì)注釋分開。注意要設(shè)置JAVADOC_AUTOBR比者QT_AUTOBRIBF為YES(3)先從文件開始注釋，然后是所在文件的全局函數(shù)、結(jié)構(gòu)體、枚舉變量、命名空間一命名空間中的類一成員函數(shù)和成員變量。(4)Doxygen無法為DLL中定義的類導(dǎo)出文檔例如：class_declspec(dllexport)CClassName:publicCObject()所生成的文檔中發(fā)現(xiàn)Doxygen無法識別出DLL中定義的類。2、Doxygen常用指令如前面所述的brief命令，還可以在注釋中加入其他Doxygen支持的指令，控制輸出文檔的排版格式，使用

7、這些指令時(shí)需要在前面加上“”或者”(JavaDoc風(fēng)格)符號，告訴Doxygen這些是一些特殊的指令，通過加入這些指令以及配備相應(yīng)的文字，可以生成更加豐富的文檔卜表列出常用的Doxygen指令:file檔案的批注說明。author作者的信息brief用于class或function的簡易說明eg：brief本函數(shù)負(fù)責(zé)打印錯(cuò)誤信息申param主要用于函數(shù)說明中，后面接參數(shù)的名字，然后再接關(guān)于該參數(shù)的說明return描述該函數(shù)的返回值情況eg:return本函數(shù)返回執(zhí)行結(jié)果，若成功則返回TRUE否則返回FLASEretval描述返回值類型eg:retvalNULL空字符串。retval!NULL非

8、空字符串。note注解attention注思warning警告信息enum引用了某個(gè)枚舉，Doxygen會(huì)在該枚舉處產(chǎn)生一個(gè)鏈接eg：enumCTest二MyEnumvar引用了某個(gè)變革,Doxygen會(huì)在該枚舉處產(chǎn)生一個(gè)鏈接eg：varCTest二m_FileKeyclass引用某個(gè)類，格式：classeg:classCTestinc/class.hexception可能產(chǎn)生的異常描述eg:exception本函數(shù)執(zhí)行可能會(huì)產(chǎn)生超出范圍的異常Modules（模塊）：Modules是一種歸組things在分離的page上的方式。組的成員可以是filenamespaceclasses,funct

9、ions,variables,enumstypedefs和defines,但也可以是其他groups。要定義一個(gè)group,應(yīng)該在一個(gè)特殊注釋塊放置defgroup。 命令的第一個(gè)參數(shù)應(yīng)該是唯一標(biāo)志該group的標(biāo)簽。要將一個(gè)entity歸為某個(gè)group的一個(gè)member在entity前放置ingroup命令。第二個(gè)參數(shù)是group的title。要避免在注釋中每個(gè)membe而放置ingroup命令， 可以將member用和時(shí)裝起來。標(biāo)記可以放置group的注釋中，也可以在一個(gè)獨(dú)立的注釋塊使用這些group的標(biāo)記符號groups也可以嵌套。如果多次使用一個(gè)group標(biāo)簽，將會(huì)出錯(cuò)。如果不希望d

10、oxygen強(qiáng)行執(zhí)行唯一標(biāo)簽，可以使用addtogroup而非defgroup。運(yùn)作方式和defgroup很像，但是如果該group已經(jīng)定義，它默認(rèn)向已存在的注釋中添加一個(gè)新的項(xiàng)。Group的title對此命令是可選的,也可以考慮使用它。/* defgroup模塊名模塊的說明文字* * /.定義的內(nèi)容/*/模塊結(jié)尾這樣可以在其他地方以更加詳細(xì)的說明添加members到一個(gè)group。注意compoundentities（例如classes,files和namespaces可以放在多個(gè)groups中，但是members例如variablesfunctions,typedefs和enmu只可以歸于

11、一個(gè)groupMemberGroups如果一個(gè)compound（例如一個(gè)class或file）有多個(gè)members通常我們希望將其groupoDoxygen已經(jīng)可以自動(dòng)按照類型和protection級別將這些things歸組在一起，但可能你會(huì)認(rèn)為僅僅這樣是不夠的或者這種缺省的方法是錯(cuò)誤的。例如你認(rèn)為有不同（語法）的類型需要?dú)w入同一個(gè)group（語意）。這樣定義一個(gè)membergroup：/塊或者使用/*/*/3、Doxygen注釋實(shí)例下述實(shí)例均以JavaDoc風(fēng)格進(jìn)行注釋，在日常規(guī)范中也推薦盡量使用JavaDoc風(fēng)格的注釋。(1)文件注釋文件不在任何東西里面，所以不能像類、函數(shù)等在上方放注釋，

12、只能用le方式定義，其格式如下：/*filefile-name* briefbriefdescription* author* author* date* version* note* detaileddescription*/表示可選項(xiàng)，表示重復(fù)0到N次，表示必須參數(shù)一般file后我們空著，Doxygen會(huì)默認(rèn)為是file所在文件的文件名。brief為簡明注釋aothor為作者列表date為日期version為版本號note為注解一個(gè)文件注釋實(shí)例：(2)類和成員注釋* classheader-fileheader-name* briefbriefdescription* author* no

13、te* detaileddescription*/如果對文件、結(jié)構(gòu)體、聯(lián)合體、類或者枚舉的成員進(jìn)行文檔注釋的話，并且要在成員中間添加注釋，而這些注釋往往都是在每個(gè)成員后面。為此,可以使用在注釋段中使用標(biāo)識。intvar;/*Detaileddescriptionafterthemember*/對一個(gè)類的注釋例子如下：classTestpublic:/*briefAenum,withinlinedocs*/enumTEnumTVal1,/*enumvalueTVal1.*/TVal2,/*enumvalueTVal2.*/TVal3/*enumvalueTVal3.*/*enumPtr,/*en

14、umpointer.*/enumVar;/*enumvariable.*/*briefAconstructor.*/Test();/*briefAdestructor.*/Test();/*briefanormalmembertakingtwoargumentsandreturninganintegervalue.*/inttestMe(inta,constchar*s);/*briefApurevirtualmember.* paraminc1thefirstargument.* paraminc2thesecondargument.* seetestMe()*/virtualvoidtes

15、tMeToo(charc1,charc2)=0;intpublicVar;/二apublicvariable.三/*briefafunctionvariable,noteDetails.*/int(*handler)(inta,intb);/*briefbriefbeforedelaration*/intm_func(inta);(3)函數(shù)注釋任何函數(shù)都必須要有簡要注釋和詳細(xì)注釋，習(xí)慣用法如下：/* briefbriefdescription* author* paramin|out* exception* return* note* detaileddescription* remarks*

16、/舉例說明：/*/三這里寫該函數(shù)的詳述信息被測試的變量（param描述參數(shù)）指向描述測試信息的字符串測試結(jié)果（return描述返回值）（本函數(shù)參考其它的相關(guān)的函數(shù)，這里作一個(gè)鏈接）描述需要注意的問題）*breifF 面是一個(gè)含有兩個(gè)參數(shù)的函數(shù)的注釋說明（簡述）inttestMe(inta,constchar*s)(4)枚舉注釋每個(gè)枚舉定義必須添加注釋，格式如下:/*Anotherenum,withinlinedocs*/enumAnotherEnumV1,/*value1*/V2/*value2*/)；(5)全局變量和全局宏全局變量和全局宏必須要有注釋，如果注釋較短，則可以在所注釋代碼上方用/

17、*briefsomebriefdescription*/或右方用/*somebriefdescription*/進(jìn)行簡要注釋。舉例如下/*/*brief這是一個(gè)全局變量。* doxygen默認(rèn)的注釋都是寫在要注釋的部分的前面，*寫在后面的注釋要加一個(gè)額外的符號,。*后面的注釋往往用來說明一個(gè)class,struct,union,orenum的成員變量* /intn;intm;/*這是另一個(gè)全局變量。寫在后面的注釋也可采用/*.*/的方式*/(6)Modules(模塊注釋)Group定義命令的優(yōu)先級(從高到低)：ingroup,defgroup,addtogroup,weakgroup。而wea

18、kgroup很像一個(gè)有低優(yōu)先級的addtogroup。它被設(shè)計(jì)為實(shí)現(xiàn)一個(gè)“l(fā)azy”的group定義方法：可以在.h文件中使用高優(yōu)先級來定義結(jié)構(gòu)，在.cpp文件中使用weakgroup這樣不會(huì)重復(fù).h文件中的層次結(jié)構(gòu)* paramina* paramins* return* seeTest()* note(note/*ingroupA*/externintVarInA;* defgroupIntVariablesGlobalintegervariables*/*/*anintegervariable*/externintIntegervariable;/*/* defgroupVariable

19、sGlobalvariables*/*/*avariableingroupA*/intVarInA;intIntegervariable;/*/如果你更喜歡Cstyle注釋。 需要注意的是所有的members必須寫在其中。 在/之前還可以加一個(gè)注釋塊， 這個(gè)注釋塊應(yīng)該包含name或者name）來指明group的header。可選的，這個(gè)注釋塊可以包含group的更詳細(xì)的信息。Membergroups不允許使用嵌套。如 果 一 個(gè) 類 中 的 某 個(gè)membergroup中 所 有 的members有 相 同 的type和protectionlevel（例如都是staticpublicmembe

20、rs）,那么這整個(gè)都會(huì)作為該type/protectionlevelgroup的subgroup顯式出來（例如，這個(gè)group作為“staticpublicmemberssection的subsection）。如果兩個(gè)或更多成員有不同的類型，那么這個(gè)group會(huì)和自動(dòng)產(chǎn)生的groups放在同一個(gè)level。Example:/*Aclass.Details*/classTest(public:/*Samedocumentationforbothmembers.Details*/voidfunc1InGroup1();voidfunc2InGroup1();/*Functionwithoutgro

21、up.Details.*/voidungroupedFunction();voidfunc1InGroup2();protected:voidfunc2InGroup2();voidTest:func1InGroup1()voidTest:func2InGroup1()/*nameGroup2* Descriptionofgroup2.*/*Function2ingroup2.Details.*/voidTest:func2InGroup2()/*Function1ingroup2.Details.*/voidTest:func1InGroup2()/*!file* docsforthisfi

22、le*/!onedescriptionforallmembersofthisgroup/!(becauseDISTRIBUTE_GROUP_DOCisYESintheconfigfile)#defineA1#defineB2voidglob_func();/下面給出一個(gè)例子程序生成說明文檔chm的對照示意圖：該例子包括一個(gè)doxytest.h和doxytest.cpp,大部分的聲明、定義、注釋都寫在doxytest.h內(nèi)。最后生成的說明文檔包括三大類，模塊、類和文件。模塊：根據(jù)項(xiàng)目需要將一組成員(包括類，函數(shù)，變量)建成一個(gè)group,在說明文檔中會(huì)以模塊的形式顯示出來。竽MyMyP-Djec

23、tP-Dject需累瑪牖總箱度鼐急盤MyProject苔蟲模陰類R R忤當(dāng)1F-SE盛卻受三坐標(biāo)坐標(biāo)類cldsscldss總noUwrChildEvgntnoUwrChildEvgnt用來溫示1 1但artflartfl，口卯再器函數(shù)*onstocuble*onstocuble& &ChildChild豈收n nt t二*i.i.conitconit費(fèi)諄 0 停工坐標(biāo)constdoitteconstdoitte& &ChCh陽SentSent二y yconstconst期喝f?f?電班壽呈EvntzmoiuseEvntzmoiuse類:類繼承關(guān)系圖:nMEA圖E

24、l生成亍五1=三月 ME1731?4.TJMyPifliftcffi 和 6類成員，可以分為成員函數(shù)和成員變量進(jìn)行查看剪 MyProjectMyProject磊魚嘉盤xkeykey, ,EvvntEvvnt：imcimc:ChHdEvm:ChHdEvmxOxOChildEventChildEventx_:x_:ChildEvtniChildEvtniChildEvsntChildEvsntChiidEventChiidEvent53=。碑地霜期 E1 打+14 力%Eu 研器監(jiān)3X室腦琮蠹富黑K K弟m m,格I I項(xiàng)MC)MC)I I期3J3J三邛烷.-.-U1U1比同生到志田堂光進(jìn)話關(guān)羸田

25、喙交藩正- -J J 文件ElEl3 3件3 3傣二必。：H H 姐 IrtjittIrtjitt三 UDiUDi，r/r/中 nfj-nfj-1 1FF1FF1VkVkdndn/，t t” ：1+11+1, ,dwryttstdwryttsth h日 w 文件成員引全津= 3 3 習(xí)習(xí) R R 寶值寶值MyProject類繼承關(guān)系類繼承關(guān)系，工通告奧紅承切表A)Dilitr2hidEvsrAA)Dilitr2hidEvsrAChiJEerrimouimouEvtntEvtnt文件立叫*痂LitLitn n福妒由Mtt生“婚盤蝴AA習(xí)MyProject自重好麗好麗1這星列出了所有支國地課 M 員,訃河田所府町文性一acticacticAnotliAnotli rChilclEvantrChilclEvant文件：doxytest.cpp中只有main函數(shù)，其他聲明與定義等放在doxytest.h中