java基礎 - 註釋標籤的使用

之前寫代碼的時候喜歡使用多行註釋書寫註釋，大體的看到默認的標籤的英文單詞，就依照英文單詞的表面意思書寫註釋，今天我仔細查閱的資料後，才發現，以前寫的都是錯誤的，爲此，我特地將此記錄下來，時刻提醒本身，不要犯相同的錯誤

1.@see：引用其餘類

@see 標籤容許用戶引用其餘類的文檔，javadoc會在其生成HTML文件中，經過@see標籤連接到其餘的文檔。

格式：

@see classname

@see fully-qualified-classname

@see fully-qualified-classname#method-name

這些標籤都會在文檔中生成一個具備超連接的「See Also」條目。可是javadoc不會檢查連接有的有效性。

2.{@link package.class#member label}

該標籤與@see很類似，只是它用於行內，而且是用「label」做爲超連接文本而不是用「See Also」

3.{@docRoot}

該標籤生產到文檔根目錄的相對路徑，用於文檔樹結構頁面的顯示超連接

4.{@inheritDoc}

該標籤從當前這個類的最直接的基類中繼承相關文檔到當前的文檔註釋中。

5.@version

該標籤的格式以下：

@version version-information

本標籤用於書寫版本信息

6.@author

該標籤格式以下：

@author author-information

本標籤用於書寫做者信息

7.@since

該標籤容許你指定程序代碼最先使用的版本，能夠在html文檔中看到它被用來指定全部的jdk版本狀況

8.@param

該標籤用於方法中，格式以下：

@param parameter-name description

parameter-name 是方法列表中的標示符，description 是可延續數行的文本

9.@return

該標籤用於方法文檔中，格式以下：

@return description

其中description用於描述返回值的含義，能夠延續數行

10.@throws

此標籤針對可能出現的拋出的異常進行描述說明，格式以下：

@throws fully-qualified-class-name description

fully-qualified-class-name爲異常的類的名字及路徑，description爲異常說明

11.@deprecated

該標籤用於指出一些舊特性已經由新特性所取代，建議用戶不要再使用這些舊特性，由於在不久的未來他們極可能被刪除，若是使用此標籤，則會引發編譯器發出警告，在javase5中，此標籤已經被@Deprecated註解所替代

 

---

 

綜上所述，來看一下具體示例吧：

 package net.test.test;
import java.io.IOException;
import com.me.mapping.Mapping;
/**
 * {@docRoot}
 * @author Dike Li
 * @since JDK 1.6
 * @version 1.0
 */
public class Test implements Mapping{
 
 /**
  * @throws IOException 
  * @see com.me.Entity.Entity
  */
 public void testLabel() throws IOException{
  
 }
 
 /**
  * @see com.me.Entity.Entity#getName
  */
 public void testSeeMethod(){
  
 }
 
 /**
  * {@link net.test.test.Test#testLink}
  */
 public void testLink(){
  
 }
 
 /**
  * {@inheritDoc}
  */
 @Override
 public void add() {
  // TODO Auto-generated method stub
  
 }
 
 /**
  * 返回相加的值
  * @param value1 參數1
  * @param value2 參數2
  * @return 返回相加的值
  * @deprecated 此方法已經被替換
  */
 public String back(String value1,String value2){
  return value1 + value2;
 }
}