Python文檔化開發(fā)注釋規(guī)范

1、1.原則在語(yǔ)言要求的地方注釋，以標(biāo)準(zhǔn)的注釋語(yǔ)法！我們禁止驚奇！ 一切規(guī)范化到誰(shuí)都可以準(zhǔn)確的猜測(cè)出止確的結(jié)果最好！(就象FreeBSD 的組織方式)注肆說明必要的倍息，我們不期望粘彩的小說在注釋中誕生！適當(dāng)?shù)陌姹緲?biāo)識(shí)盡吏用CVS等版本管理系統(tǒng)I動(dòng)提供的解析因?yàn)槿绻T個(gè)兒來(lái)寫的話難以統(tǒng)一修改適當(dāng)?shù)脑O(shè)計(jì)思路描述適當(dāng)?shù)乃惴ㄔO(shè)訃描述2.文檔化標(biāo)簽山于開發(fā)語(yǔ)言非常&富，所以選擇了最通用和穩(wěn)定的文檔化IJI來(lái)支持：PoxiiQcnDoxyGen 圧種支持 C-H-, C. Java. Objective-C. IDL (Corba and Microsoft flavors) 以及PHP. C# a

2、nd D等等語(yǔ)言的文檔化匸具.成熟，功能強(qiáng)大，支持廣泛捷至于提供了圖形界I何的管理工具對(duì)于所冇支持多行注禪的語(yǔ)言其實(shí)都可以應(yīng)用epydoc是純Python實(shí)現(xiàn)的Python專用文檔化工貝與Python結(jié)合非常門然，穩(wěn)定，可擴(kuò)展2.1.基礎(chǔ)標(biāo)簽命令僅僅列舉我們推薦使用的文檔化標(biāo)簽，進(jìn)一步的標(biāo)簽命令，請(qǐng)自行進(jìn)入相關(guān)頁(yè)面學(xué)習(xí)EpyDoc注釋規(guī)范DoxyGen注釋規(guī)范epydoc解析支持的標(biāo)簽規(guī)范口錄“常用命令py文獻(xiàn)信息py狀態(tài)仁息 py模塊信息 pyph式仁息 py捉醉信息 py關(guān)聯(lián)仁息py標(biāo)簽恪式 py注禪風(fēng)格3. py常用命令講述堆本的常用標(biāo)簽命令3.1. py文獻(xiàn)信息author:.作者li

3、cense:.版權(quán)contact:聯(lián)系32 py狀態(tài)信息version:.版本推薦使用$IdStodo ver:改進(jìn)可以指定針對(duì)的版本3.3. py模塊信息var v:模塊變量V說明type v:.模塊變量類型V說明3.4. py函式信息param p:參數(shù)p說明type v:.參數(shù)p類型說明return: .返回值說明rtype v:.返回值類型說明3.5. py提醒信息notc:注解(attention:.注意bug:.問題warning:I s«e：參考資料36 py關(guān)聯(lián)信息約圮文檔化標(biāo)簽的語(yǔ)法epydoc支持三種標(biāo)簽的語(yǔ)法！Epytext ©tag:內(nèi)容RStruc

4、tur（iTi:t :tag:內(nèi)容Javadoc tag 內(nèi)容為了簡(jiǎn)化學(xué)習(xí)，在新浪標(biāo)準(zhǔn)化開發(fā)中我們推薦統(tǒng)一使用 ©tag:內(nèi)容格式5. py注釋風(fēng)格約定文檔化標(biāo)簽放置依照Python本身的注釋風(fēng)格口然的進(jìn)行1 # OtTool.py文件(模塊)頭部2 *'小Otter Tools main script3 version: $ld$4 author: UZoom Quiet<mailto:Zoom Qinet>5 see:參考資料鏈接等等67 import sys,string8 class ottool:9Otter Tools 主類10-組織其它小工具，完成任

5、務(wù)11todo:計(jì)劃完成12HUM13def mit (self):14相關(guān)模塊，初始化（為前比較簡(jiǎn)也 對(duì)象初始化時(shí)就完成所冇任務(wù)）15-應(yīng)用OtCUI參數(shù)理解;獲得有效變量1617self.cui = OtCUI.otcuiO18.lnit._.py中的注釋成為包文檔文件頭部注釋成為模塊文檔緊貼class聲明后的注釋成為類文檔 緊貼def聲明麻的注釋成為函式文檔6. dox常用命令講述基本的常用標(biāo)簽命令6.1. dox文獻(xiàn)信息6.2. dox狀態(tài)信息version 版本推薦使用$IdStodo .改進(jìn),可以指定針對(duì)的版本6.3. dox模塊信息var 模塊變戢說明typedef.模塊變雖:類

6、型說明6.4. doz函式信息param p .參數(shù)p說明arg .列表說明參數(shù)信息return .返回值說明retva.返冋值類熨說明6.5. dox提醒信息note .注解attention 注意bug 問題warning .警告6.6. dog關(guān)聯(lián)信息| SN 參考資料7. dox標(biāo)簽格式約定文檔化標(biāo)簽的語(yǔ)法epydoc支持兩種標(biāo)簽的語(yǔ)法！doxygen tag 內(nèi)容Javadoc tag 內(nèi)容為了簡(jiǎn)化學(xué)習(xí)，在新浪標(biāo)準(zhǔn)化開發(fā)中我們推薦統(tǒng)-使用©tag:內(nèi)容格式8. dox注釋風(fēng)格約定文檔化標(biāo)簽放置依照C/C+ JAVA類別語(yǔ)言注釋風(fēng)格I然的進(jìn)行* 一個(gè)示范類.描述在此*/cla

7、ss Test public:/*個(gè) enum.*詳細(xì)描述可以多行*/cnum TEnuin Wall,/*單行注釋拿/*eniuiiPtr, /< enum pomter Details. */ /"構(gòu)適器函式詳細(xì)描述可以多行/Test();/" 一個(gè)普通函式描述和參數(shù)等等的做述* parama整數(shù)參數(shù) param s字指針參數(shù) see TestO參看* retum返冋值描述/int testMe(mt a .const char Ss);/"純虛成員函式* see testMeO 參看 paramc 第參數(shù)* param c2 第參數(shù)/virtual v

8、oid testMeToo(char c 1 .char c2) = 0;/"* 一個(gè)公共變戢拿詳細(xì)描述拿/mt publicXir;DoxyGen支持幺種注釋聲明僅僅是在標(biāo)準(zhǔn)堆礎(chǔ)上添加一點(diǎn)兒:JavaDoc樣式的:/* . text.*/Qt樣式的:/!.text*/C+樣式的:/ text./or/!/! - text /!我們推薦簡(jiǎn)化的Qt風(fēng)格 /!引發(fā)的多行注釋*/止常結(jié)束8丄輸出美化控制可以通過簡(jiǎn)單的約定來(lái)美化文檔的輸出但是不要深迷F此IpyDoc注釋輸出控制DoxyGen注釋輸出控制目錄塊結(jié)構(gòu)段落列表章節(jié)第1章章節(jié)1.1第2章引用塊行內(nèi)修飾特殊標(biāo)簽URLs交叉引用警告9.

9、塊結(jié)構(gòu)象文章分章節(jié)一樣注釋文本也能定義齊種語(yǔ)義區(qū)塊9.1.段落簡(jiǎn)也的使用空行就好def example。：UM99這是第一段.段落可以包含多行并可以包含有1彳亍內(nèi)修飾這是第二段.段落間通過空行來(lái)區(qū)分將生成為：這是第一段.段落可以包含多行并可以包含有行內(nèi)修飾這是第 二段.段落間通過空行來(lái)區(qū)分9.2.列表象MomXIom等等結(jié)構(gòu)化文本一樣通過縮進(jìn)來(lái)聲明便川 數(shù)字 或Ri T來(lái)引導(dǎo)列表項(xiàng)可以混合def example():此為段落.L此為列表項(xiàng)此為子列表子列表第二項(xiàng)-此為次層列表，同樣可以繼續(xù)列表卜去只耍有一致的縮進(jìn)2.此為列表第二項(xiàng)町以包含段落和測(cè)試引用»> print眥為測(cè)試引用

10、語(yǔ)御此為測(cè)試引用語(yǔ)句此為第二段1IMII將生成文檔為:此為段落.此為列表項(xiàng)此為子列表子列表第二項(xiàng)此為次層列表，同樣可以繼續(xù)列表下去 只要有一致的縮進(jìn)此為列表第二項(xiàng)可以包含段落和測(cè)試引用»> print'jit為測(cè)試引用語(yǔ)句，此為測(cè)試引用語(yǔ)句此為第二段9.3.章節(jié)使丿U ReStructuredText結(jié)構(gòu)化文本的聲明力式def example():此段不在任何章節(jié)中.第1章這為第1章中的段落章節(jié)1.1此為章節(jié)1.1中的段落第2章此為第2帝中的段落.II將生成:此段不在任何章節(jié)中.9.3丄第1章這為第1章中的段落此為章節(jié)1.1中的段落9.3.2.第 2 章此力第2章中的段

11、落.9.4.引用塊同樣是利川ReStructuredText的引川川明 def example():使用“：'引出引用塊:：原文/ /引用塊此為在引用塊后的段落 還足空行來(lái)區(qū)分.!»生丿戈的文檔類似:使用匕："引出引用塊： 原文/引用塊此為在引用塊后的段落還足空行來(lái)區(qū)分.10-行內(nèi)修飾簡(jiǎn)單的字體聲明def exaniple():IB行內(nèi)修飾可以嵌套在多行內(nèi).1斜體-B加重C源代碼Cmy_dict=l:2,3:4_將生成類似文檔：行內(nèi)修飾町以嵌套在多行內(nèi).斜體 加重 源代碼切 換 行 號(hào) 顯 示lang=en id=CA-a2c6d35298ec49bd0ec7822

12、5786ef69c7c95al2b_000 dir=ltr1my_dict=12 3:410.L特殊標(biāo)簽10.L1. URLsdef exaniple():-Uvww.python.OTg-U-UThe epydoc homepage<http:/ > UThe BIPython homepage vwww.python OTg>UEdvard Loper<mailto:edloper >-對(duì)應(yīng)生成文檔：pythonhttp”mwv python org The epydoc

13、homepage The Python hont即aj址 Edward Loper10.1.2.交叉引用Ltext<objet>可以門動(dòng)生成到其它對(duì)象的文檔!Oi鏈接 text處是說明文字<object>是貝體對(duì)象的名稱，類/函式/變戢名U.警告當(dāng)然對(duì)于意外悄況.epydoc不會(huì)崩潰，只是進(jìn)行警告，你町以根 據(jù)提示進(jìn)行修正12.塊結(jié)構(gòu)彖文章分章節(jié)一樣 注釋文本也能定義以種語(yǔ)義區(qū)塊111.段落par命令引出/! class Test普通文字©par用戶定義第一段.段落可以包含多行par這是第二段.段落間通過空行來(lái)區(qū)分*/H體實(shí)例參考：par命令 輸出的HTML1

14、2.2.列表h命令引發(fā)可以混合其它格式命令li c AlignLeft left alignment.li c AlignCenter center alignment.li c AlignRight right aligmneiit無(wú)類型的列農(nóng)項(xiàng)也支持具體實(shí)例參考:11命令12.3.章節(jié)section命令引發(fā)不過，只能在©page命令后作用即通過©page命令，聲明創(chuàng)建一個(gè)相關(guān)頁(yè)面,內(nèi)容將組織到最終的相關(guān)頁(yè)面"中,與 Todo Bug列表頁(yè)面等等并列在一起！例如 /! page pagel A documentation pageLea&ng text.

15、section sec An example sectionThis page contains the subsections ref subsection 1 and ref subsection?.For more info see page ref page2 subsection subsectionl The first subsection Text.More text./*! page page? Another page Even more info./將生成:pape命令 包含了section 章subsection 節(jié)ref提及三個(gè)命令的使川12.4.引用塊code 和

16、endc<xle fl4ih類似：/*!par _doAllOiiLoad() ©param 全局?jǐn)?shù)組 g_onload ietum oid逐條調(diào)用lL知的函數(shù)人_八©note動(dòng)態(tài)加載的模塊中,一些函數(shù)需要o nLoadOjr件觸發(fā);但是code window onload= new Function ( 'myFunctoinO：")：endcode將會(huì)重新注冊(cè)onLsdO韋件的運(yùn)行函數(shù).致使不能簡(jiǎn)單的使不同的模塊中需要的不確定 數(shù)口的onLoadO觸發(fā)函數(shù)疊加注冊(cè)！13.行內(nèi)修飾簡(jiǎn)單的字體聲明13.1. bb文字 生成:<b> 文字 </b>13.2. cC文字生成：<tt> 文字v/tt>n生成:<br/>13.4.特殊標(biāo)簽針對(duì)PHP語(yǔ)言，doxygen仃兒個(gè)標(biāo)簽命令，需耍關(guān)注13.