Java 教程《語法說明》註解

Java 教程《語法說明》註解


■ 註解
/* This is a comment. */
// This is also a comment.
/** 文件式註解 */

[說明]
1. 在 /* */ 或 /** */ 內的文字或 // 後的文字都會被 Java compiler 忽略
2. 建議的註解內容：
　A) 每一程式的頂端的註解：
　　　1> 程式名稱
　　　2> 設計者名稱
　　　3> 最後版本的日期
　　　4> 該程式的描述
　B) 在 method 開頭前的註解：
　　　1> 類別名稱和method名稱
　　　2> 該method 的作用目的
　　　3> 任何有關該method須注意之處，例如錯誤狀況處理或該method可處理或無法處理的特別之處
　C) variable 代表的意義
3. 文件式註解
　A) javadoc.exe 可解析程式碼內的註解文件。
　B) Javadoc.exe 的使用有兩種主要型式：內嵌式HTML，或是文件標籤(doc tag，以@ 符號為首的命令，這個符號必須置於
　　 註解的最前面，也就是扣掉最前面的* 之後的最前面處)。
　C) 文件式註解內容有三種型式，註解位置需分別出現於 class、variable 和 method 之前。

註解標籤 與 類別相關的標籤
　 @version 版本編號(須使用 -version 選項)
　 @author  作者姓名(須使用 -author 選項)
‧ 與方法相關的標籤
　@ param、 @return、 @throws、 @exception

‧ 一般標籤
　 @see 表示有所關聯的類別或方法；也可以使用標記(label)或超鏈結，或是產生內嵌的文字鏈結(鏈結不會出現在 See Also 標題下方)
　　　A) 參照其它類別
　　　　　@see PackageName.ClassName
　　　B) 參照另一個方法
　　　　　@see ClassName#methodName
　　　　　@see PackageName.ClassName#methodName(Type id, Type id)
　　　C) 使用超鏈結　
　　　　　@see <a href="LinkURL">Link</a>
　　　D) 使用標記
　　　　　@see name label
　　　E) 產生內嵌的文字鏈結
　　　　　{ @see API-Name label }

[限制]
1. 不能使用巢狀(nested)註解
2. javadoc.exe 只會針對存取層級為 public 或 protected 的 members 進行註解文件的處理，不會處理 private 層級
　的 members，除非打開 -private 選項，一併處理 private 成員，因為只有宣告為 public 和 protected 的成員，
　才能被外界存取；而針對 class 所做的註解，都會處理並輸出。

[範例]
/** class 的註解 */
public class MyClassA {
　　/** variable 的註解 */
　　public int instancevariableA;

　　/** method 的註解 */
　　public void instanceMethodB( );
}

[範例]
/** 
  * Doubles an integer 
  * 
  * @param k     The integer to double 
  * @return    An integer containing the doubled value 
  */ 
public int double( int k ) { 
　　return 2*k; 
} 

[範例]
/**
*  This is a sample comment
*  @auther : ABC
*  @version 1.0
*  @returns java.lang.String
*  @throws Exception
*/