代碼形象 JAVA

javadoc註釋規範

備註：本文結合了許多篇文章的內容加上自己的理解和經驗，將很多零散的知識點，總結和統一整理與此。

你必須寫註釋而且按照項目規範來的寫註釋的理由

javadoc註釋規範就是指文檔註釋，包括類、接口、方法、屬性等的說明，在一個團隊項目開發中，統一規範的註釋很重要，對於自己以後的查看源碼也極有幫助，如果沒有相應的註釋，那麼給團隊合作、自己查看源代碼都會帶來非常大的工作量。

而且需要了解的是，java doc編譯生成的文檔是html格式的，所以，我們就得遵循一些規範，不至於生成的文檔雜亂無章。

要注意的是，生成的文檔是 HTML 格式，而這些 HTML 格式的標識符並不是 javadoc 加的，而是我們在寫註釋的時候寫上去的。比如，需要換行時，不是敲入一個回車符，而是寫入＜br＞，如果要分段，就應該在段前寫入＜p＞。

因此，格式化文檔，就是在文檔註釋中添加相應的 HTML 標識。

文檔註釋的正文並不是直接複製到輸出文件 (文檔的 HTML 文件)，而是讀取每一行後，刪掉前導的 * 號及 * 號以前的空格，再輸入到文檔的。如 /**

* This is first line. ＜br＞

***** This is second line. ＜br＞ This is third line. */

編譯輸出後的 HTML 源碼則是 This is first line. ＜br＞ This is second line. ＜br＞ This is third line.

前導的 * 號允許連續使用多個，其效果和使用一個 * 號一樣，但多個 * 號前不能有其它字符分隔，否則分隔符及後面的 * 號都將作爲文檔的內容。

那麼，哪些地方需要寫註釋？

基本註釋

（1）類和接口

（2）構造方法

（3）普通方法（實體類對象的setter、getter方法不用註釋）

（4）全局變量

（5）字段、屬性

特殊註釋

（1）典型算法

（2）在代碼不明晰處

（3）在代碼修改處加上修改標識註釋

（4）在循環和邏輯分支組成的代碼中註釋

（5）爲他人提供的接口必須詳細註釋

註釋的格式、類型

單行註釋：//……

塊註釋：/*……*/

文檔註釋：/**……*/

而javadoc，顧名思義，則是更多的是針對文檔註釋，本文也將大部分講文檔註釋的java規範，那麼，我們首先要了解，javadoc裏的標記

Tag & Parameter	Usage	Applies to	Since
@author name	Describes an author. 描述作者	Class, Interface
@version version	Provides version entry. Max one per Class or Interface. 版本條目，每個類或接口最多有一個	Class, Interface
@since since-text	Describes since when this functionality has existed. 描述這個功能塊從何時有的	Class, Interface, Field, Method
@see reference	Provides a link to other element of documentation. 提供鏈接到其他文檔元素的鏈接	Class, Interface, Field, Method
@param name description	Describes a method parameter. 描述一個參數	Method
@return description	Describes the return value. 描述返回值	Method
@exception classname description @throws classname description	Describes an exception that may be thrown from this method. 描述該方法可能拋出的異常	Method
@deprecated description	Describes an outdated method. 描述一個過期的方法	Method
{@inheritDoc}	Copies the description from the overridden method. 從複寫方法出拷貝來得描述	Overriding Method	1.4.0
{@link reference}	Link to other symbol. 連到其他的引用	Class, Interface, Field, Method
{@value}	Return the value of a static field. 返回一個靜態作用域的值	Static Field	1.4.0

下面爲參考舉例，可在eclipse或myeclipse中設置模板，下文有介紹（註釋一定要緊跟者類、方法、屬性）

1、類和接口的註釋


/**
 * 
 * @ClassName Test_Singleton.java
 * @Description TODO
 * @Author 先
 * @Time 2017年3月25日 下午3:12:43
 *
 */
public class Test {
    //……
}

2、構造方法的註釋


/**
 * 
 * @Title: Test
 * @Description: TODO
 */
public Test(){
		
}

3、方法的註釋


/**
 * 
 * @Title: test
 * @Description: TODO
 * @param para1
 * @param para2
 * @return String
 */
public String test(Integer para1,String para2){
		
	return para2;
}

4、屬性、字段、全局變量的註釋


/**
 * (說明內容)
 */
private String name;
/**
 * (說明內容)
 */
private final Integer id;

一些標記的相關使用說明

1、@see

@see 的句法有三種：

@see 類名

@see #方法名或屬性名

@see 類名#方法名或屬性名


/**  
 * @see  java.lang.String 
 * @see  #str 
 * @see  #str() 
 * @see  #main(String[]) 
 * @see  java.lang.Object#toString() 
 */  
 
public classTestJavaDoc  {   
 
private Stringstr; 
 
public voidstr(){   }
 
public staticvoid main(String[] args){   }
 
}

生成的文檔的相關部分如下圖

2、@author、@version

這兩個標記分別用於指明類的作者和版本。缺省情況下 javadoc 將其忽略，但命令行開關 -author 和 -version 可以修改這個功能，使其包含的信息被輸出。

這兩個標記的句法如下：

@author 作者名

@version 版本號

其中，@author 可以多次使用，以指明多個作者，生成的文檔中每個作者之間使用逗號 (,) 隔開。@version 也可以使用多次，只有第一次有效，生成的文檔中只會顯示第一次使用 @version 指明的版本號。如下例


/**  
 * @author Fancy
 * @author Bird
 * @versionVersion 1.00
 * @versionVersion 2.00
 */ 
 
public classTestJavaDoc {}

生成文檔的相關部分如圖

3. @param、@return 和 @exception

這三個標記都是隻用於方法的。@param 描述方法的參數，@return描述方法的返回值，@exception 描述方法可能拋出的異常。它們的句法如下：

@param 參數名參數說明

@return 返回值說明

@exception 異常類名說明

每一個 @param 只能描述方法的一個參數，所以，如果方法需要多個參數，就需要多次使用 @param 來描述。

一個方法中只能用一個 @return，如果文檔說明中列了多個@return，則 javadoc 編譯時會發出警告，且只有第一個 @return 在生成的文檔中有效。

方法可能拋出的異常應當用@exception 描述。由於一個方法可能拋出多個異常，所以可以有多個 @exception。每個 @exception 後面應有簡述的異常類名，說明中應指出拋出異常的原因。需要注意的是，異常類名應該根據源文件的 import 語句確定是寫出類名還是類全名。示例如下：


public class TestJavaDoc {  
 
/** 
 * @param n a switch 
 * @param b excrescent parameter 
 * @return true or false 
 * @return excrescent return 
 * @exception java.lang.Exception throw when switch is 1
 * @exception NullPointerException throw when parameter n is null 
 */ 
 
public boolean fun(Integer n) throws Exception { 
    switch (n.intValue()) { 
        case 0:  break;   
        case 1: throw new Exception("Test Only"); 
        default:  return false; 
      } 
      return true; 
   }
}