1、Javadoc的獲取
只能從相應的JDK中取得,安裝後在bin目錄下。具體如下:
* Javadoc 1.4 is included in Java 2 SDK, Standard Edition v 1.4
* Javadoc 1.3 is included in Java 2 SDK, Standard Edition v 1.3
* Javadoc 1.2 is included in Java 2 SDK, Standard Edition v 1.2
* Javadoc 1.1 is included in JDK 1.1
2、文檔注釋編寫(principles)
Java平台API文檔由源碼中的文檔注釋定義,且任何此類文檔皆從此類注釋取得
Java平台API文檔是調用者(caller)和實現之間的契約(contract)
除非另有說明,Java平台API文檔聲明(assertion)應為與具體實現無關(implelementation-independent)
Java平台API文檔應有足夠的聲明,以使得軟件質量保證部門能寫出完全的JCK (Java Compatibility Kit)測試。
3、文檔注釋編寫細則
每個文檔注釋的第一句,應是個概要句,簡明但無遺地描述API項。第一句在第一個後跟空格的點號前結束。當句中出現非結束意義的點加空格時,需要空格進行轉義,如 等。
自動重利用父類/接口方法(method)的注釋,當(1)一個類方法重寫(override)父類的方法時,或(2)一個接口方法重寫父接口的方法時,或(3)一個類方法實現一個接口方法時。如果當前方法沒文檔注釋,則從父方法復制,如果有,則不復制而是前兩者有小標題 "Overrides",後者有"SpecifIEd by".
用...
來標注關鍵詞或名字
節約使用行內鏈接{@link}
對方法和構建函數的說明,要去掉括號
可以為了簡短使用短語而不是句子
使用第3人稱而不是第2人稱
以一個動詞短語開始對一個方法的描述
對類/接口/字段(fIEld)的描述,可以忽略主語
用"this"而不是"the"來引用從當前類生成的對象
不要僅是簡單地把API名字裡的單詞展開來做描述,要增加一些信息。
當作用"fIEld"一詞時,注意它易引起混淆
避免拉丁語縮寫
標簽順序
@author,多個作者時按參考修改代碼的年代為序
@version
@param,多個參數時以方法聲明中的順序為序,單個@param後跟參數名(不要相應的類型),再加描述
@return
@exception,多個異常時以異常名字的字母順序為序
@see,多個參見時據 #field,#Constructor(Type, Type...),#Constructor(Type id, Typeid...),#method(Type, Type,...),#method(Type id, Type, id...),Class,Class#field,Class#Constructor(Type, Type...),Class#Constructor(Type id, Type id),Class#method(Type, Type,...),Class#method(Type id, Type id,...),package.Class,package.Class#fIEld,package.Class#Constructor(Type, Type...),package.Class#Constructor(Type id, Type id),package.Class#method(Type, Type,...),package.Class#method(Type id, Type, id),package排序
@since
@serial
@deprcated
@param和@return(當返回不是void時)都是必須的.