Java doc註釋

經常使用Java註釋標籤（Java comment tags）

@author 做者

適用範圍：文件、類、方法

（多個做者使用多個@author標籤標識，java doc中顯示按輸入時間順序羅列。）
例：* @author Leo. Yao

@param 輸入參數的名稱 說明

適用範圍：方法

例：* @param str the String用來存放輸出信息。

@return 輸出參數說明

適用範圍：方法

例： * @return true執行成功;

​ false執行失敗.

@since JDK版本

用於標識編譯該文件所須要的JDK環境。

適用範圍：文件、類

例： * @since JDK1.6

@version 版本號

用於標識註釋對象的版本號
適用範圍：文件、類、方法
例： * @version 1.0

@see 連接目標

表示參考。會在java 文檔中生成一個超連接，連接到參考的類容。
用法
@see #field
@see #Constructor(Type, Type...)
@see #Constructor(Type id, Type id...)
@see #method(Type, Type,...)
@see #method(Type id, Type, id...)
@see Class
@see Class#field
@see Class#Constructor(Type, Type...)
@see Class#Constructor(Type id, Type id)
@see Class#method(Type, Type,...)
@see Class#method(Type id, Type id,...)
@see package.Class
@see package.Class#field
@see package.Class#Constructor(Type, Type...)
@see package.Class#Constructor(Type id, Type id)
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type id, Type, id)
@see package

@throws 異常

標識出方法可能拋出的異常

適用範圍：方法

例： * @throws IOException If an input or output exception occurred

@deprecated廢棄

標註此類/接口、方法、字段已經被廢止

適用範圍：文件、類、方法

@link 連接地址

連接到一個目標，用法相似@see。但常放在註釋的解釋中形如{@link …}

/**
    - @deprecated      As of JDK 1.1, replaced by
    - {@link #setBounds(int,int,int,int)}
 */

Java註釋的使用順序

• @author (classes and interfaces only, required)
• @version (classes and interfaces only, required. See footnote 1)
• @param (methods and constructors only)
• @return (methods only)
• @exception (@throws is a synonym added in Javadoc 1.2)
• @see
  
• @since
  
• @serial (or @serialField or @serialData)
• @deprecated (see How and When To Deprecate APIs)

常見註釋模板

類（接口）註釋

​```java
/**

• 類的描述
• @author Administrator
• @Time 2012-11-2014:49:01
• */
  public classTest extends Button {
  ……
  }

```

方法註釋

public class Test extends Button {
  /**

- 爲按鈕添加顏色
- @author Administrator
- @param color
- @return
- @exception  (方法有異常的話加)
- @Time2012-11-20 15:02:29
*/
  public voidaddColor(String color){
……
  }
}

全局變量註釋

public final class String
   implements Java.io.Serializable, Comparable<String>,CharSequence
{
   /** The value is used for characterstorage. */
   private final char value[];
   /** The offset is the first index of thestorage that is used. */
   private final int offset;
……
}

字段/屬性註釋

public class EmailBody implements Serializable{
   private String id;
   private String senderName;//發送人姓名
   private String title;//不能超過120箇中文字符
   private String content;//郵件正文
   private String attach;//附件，若是有的話
   privateSet<EmailList> EmailList;
……
}