程序師世界是廣大編程愛好者互助、分享、學習的平台,程序師世界有你更精彩!
首頁
編程語言
C語言|JAVA編程
Python編程
網頁編程
ASP編程|PHP編程
JSP編程
數據庫知識
MYSQL數據庫|SqlServer數據庫
Oracle數據庫|DB2數據庫
 程式師世界 >> 編程語言 >> JAVA編程 >> 關於JAVA >> 在Java源代碼中為Javadoc編寫文檔注釋

在Java源代碼中為Javadoc編寫文檔注釋

編輯:關於JAVA

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時)都是必須的.

  1. 上一頁:
  2. 下一頁:
Copyright © 程式師世界 All Rights Reserved