2013-07-19

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 idType 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
*/

沒有留言:

張貼留言