全面解析Java中的註解與注釋_java

註解
一、什麼是 Annotation？ （註解 or 注釋）
Annotation, 準確的翻譯應該是 -- 註解。 和注釋的作用完全不一樣。
Annotation 是JDK5.0及以後版本引入的一個特性。 與類、介面、枚舉是在同一個層次，可以成為java 的一個類型。
文法是以@ 開頭
簡單來說，
注釋是程式員對原始碼的類，方法，屬性等做的一些記憶或提示性描述(比如這個方法是做什麼用的)，是給人來看的。
註解則是Java 編譯器可以理解的部分，是給編譯器看的。
舉個簡單的例子來看一下註解的使用和作用。
@Override 是比較常見的Java 內建註解，它的作用就是在編譯代碼的時候檢查子類中定義的方法是否正確。

package annotation;  public abstract class Animal {    public abstract void eat(); } package annotation;  public class Cat extends Animal{    @Override   public void eat(String food) {    } } 

這裡在子類Cat中 eat 方法被註解為覆寫父類的方法， 但是卻比父類方法多出一個參數。
如果是在Eclipse 在編輯的話， 直接就會有紅色叉叉提示。(代碼編譯會通不過)。
如果去掉@Override的註解的話， 編譯沒問題， 但是Cat 中eat方法就是這個類的一個新的方法了，而不是從父類繼承的了。

二、常見的Java 內建註解
包含@Override ， 還有哪些常見的Java內建註解？
1. @Deprecated
註解為不建議使用，可以用在 方法和類上。
基本上這種方法和類都是因為升級或效能上面的一些原因廢棄不建議使用，但是為了相容或其他原因，還必須保留。
所以就打上這個註解。
在Java 本身的API中就有很多這樣的例子， 方法打上了這個註解，進到Source code 會看到替代的新的方法是哪個。
在eclipse 中編寫code時，添加此註解的方法在聲明和調用的地方都會加上刪除線。

2.@Override

3.@SuppressWarnings
忽略警告。
如果你的code在轉型或其他的部分有一些警告的話，但是你又想忽略這些警告，就可以使用這個註解了。
1)deprecation 使用了不贊成使用的類或方法時的警告

2)unchecked 執行了未檢查的轉換時警告

3)fallthrough 當使用switch操作時case後未加入break操作，而導致程式繼續執行其他case語句時出現的警告

4)path 當設定一個錯誤的類路徑、源檔案路徑時出現的警告

5)serial 當在可序列化的類上缺少serialVersionUID定義時的警告

6)fianally 任何finally子句不能正常完成時警告

7)all 關於以上所有情況的警告

三、自訂註解
除了Java本身提供的內建註解， Java 還提供了定製自訂註解的功能。
定義的方式就是使用註解定義註解， 用來定義註解的註解稱為元註解。
主要的元註解有以下四個：@Target ；@Retention；@Documented；@Inherited
1. @Target 表示該註解用於什麼地方，使用在類上，方法上，或是屬性等
可能的 ElemenetType 參數包括：
ElemenetType.CONSTRUCTOR 構造器聲明
ElemenetType.FIELD 域聲明（包括 enum 執行個體）
ElemenetType.LOCAL_VARIABLE 局部變數聲明
ElemenetType.METHOD 方法聲明
ElemenetType.PACKAGE 包聲明
ElemenetType.PARAMETER 參數聲明
ElemenetType.TYPE 類，介面（包括註解類型）或enum聲明
2. @Retention 表示在什麼層級儲存該註解資訊
可選的 RetentionPolicy 參數包括：
RetentionPolicy.SOURCE 註解將被編譯器丟棄
RetentionPolicy.CLASS 註解在class檔案中可用，但會被VM丟棄
RetentionPolicy.RUNTIME VM將在運行期也保留注釋，因此可以通過反射機制讀取註解的資訊。
3. @Documented ，產生doc時，是否包含此註解
將此註解包含在 javadoc 中
4.  @Inherited
允許子類繼承父類中的註解
看一些簡單定義的例子：

package annotation;  import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Inherited; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target;  @Target(ElementType.METHOD) public @interface MyAnnotation {   String value(); }  @Retention(RetentionPolicy.SOURCE)  @interface MyAnnotation1 { }   @Retention(RetentionPolicy.CLASS)  @interface MyAnnotation2 {}   @Retention(RetentionPolicy.RUNTIME)  @interface MyAnnotation3 {}   @Documented @interface MyAnnotation4 {}        @Inherited @interface MyAnnotation5 { } 

四、使用例子：

package annotation;  import java.lang.annotation.Annotation;  @MyAnnotation3 public class TestAnnotation {   public static void main(String[] args) {     // TODO Auto-generated method stub     Annotation annotation = TestAnnotation.class.getAnnotation(MyAnnotation3.class);     System.out.println(annotation.toString());   }  } 

列印出結果： @annotation.MyAnnotation3()
以上例子如果替換使用 MyAnnotation1 和 MyAnnotation2 的話， 則取到的annotation的值為空白，這就是RetentionPolicy 不同的差別。

五、Annotation的作用

介紹到此，可以總結一下Annotation的作用了。
基礎的大致可以分為三類:
1. 編寫文檔
2. 程式碼分析
3. 編譯檢查
但是，開源架構對其賦予了更多的作用
比如：
Hibernate,註解配置，

@Column("aa") private String xx; 

這個類似於XML配置，簡化程式中的配置
相對與把一部分中繼資料從XML檔案移到了代碼本身之中，在一個地方管理和維護。
內部如何?的？ -- java 反射機制，類似與以上例子。

注釋
雖然註解、注釋只相差一個字，但是用法就差異很大。
還是那句話， 註解給編譯器看， 注釋是給人看的。
基於此的話， 對於一個方法來說：
1. 把這個方法的作用， 輸入，輸出描述清楚就可以了，更多的可以加上一些作者呀，版本呀這樣一些資訊
2. 注釋編排的美觀一些
做到這兩點應該就可以了。 舉個例子：

/******************************************************************************* * NAME:     usage * DESCRIPTION: XXX * ARGUMENTS:  N/A * RETURN:    * AUTHOR:    oscar999 * VERSION:   V0.1 *******************************************************************************/ 

看上去這是一個不錯的注釋^^.

但是對於Java 語言來說， 注釋被賦予了更多的功能。 就是你可以使用javadoc 這個功能把代碼中的注釋匯出到  html 的檔案中。
如果你的代碼是共用性很高的代碼的話， 這份文檔就是一份API的參考文檔， 類似Java API.
所以， 要產生出這樣的文檔，就要遵循java 定義的一些注釋規範， 才能產生出規範的文檔出來。

一、Java 類方法的標準注釋
還是從類的方法的注釋說起。

  /**    * Read a line of text. A line is considered to be terminated by any one    * of a line feed ('\n'), a carriage return ('\r'), or a carriage return    * followed immediately by a linefeed.    *    * @param   ignoreLF1 If true, the next '\n' will be skipped <pre code_snippet_id="74911" snippet_file_name="blog_20131120_2_8365599" name="code" class="java">   * @param   ignoreLF2 If true, the next '\n' will be skipped</pre>   *   * @return   A String containing the contents of the line, not including   *       any line-termination characters, or null if the end of the   *       stream has been reached   *   * @see    java.io.LineNumberReader#readLine()   *   * @exception IOException If an I/O error occurs   */ 

（不去關注以上注釋的意義，只關注其定義的樣式）
1. 首先看最上面的 “Read a line of text.  A line .. ” 這一段是對這個方法的一些描述。

第一個句號前面的部分， 也就是 “Read a line of text.” 會出現在 “方法摘要” 中

2. @param 定義的是方法的輸入參數，（可以添加多個）出現在“ 方法詳細資料” 中。（參數和參數描述之間使用空格隔開， 在產生的文檔中轉成了  -）

3. @return  傳回值的描述
4. @see  參考的描述
5. @exception 異常拋出的描述
美觀考慮， 不同類的標籤可以換一行顯示， 比如 @param 和 @return 直接空一行。

二、Java 類標準注釋
類的注釋和方法注釋的格式基本相同。 區別的地方：
1. 放置的位置不同。 類的注釋放在類定義的上面， 方法的注釋放在方法定義的上面。
2. 類的注釋比較會使用   @version  @author  @since 這樣的標籤。
看模板

/** will buffer the input from the specified file. Without buffering, each * invocation of read() or readLine() could cause bytes to be read from the * file, converted into characters, and then returned, which can be very * inefficient. * * * Test Description * * <p> Programs that use DataInputStreams for textual input can be localized by * replacing each DataInputStream with an appropriate BufferedReader. * * @see FileReader * @see InputStreamReader * * @version 0.1, 11/20/13 * @author  oscar999 * @since  JDK1.5 */ 

doc 中顯示的效果是：
同樣， 描述的第一句出現在“類概要”中。

類的詳細資料顯示如下：

值得注意的是 description 中<p> 的使用。 如果沒有加<p> , 在java code 中不管是否有換行，產生的doc 中都不換行。 加上<p> 的話， doc 中出現換行。

三、補充
補充一下， 產生javadoc的方法：
1. 命名行方式：  javadoc  + 參數

2. 使用Eclipse IDE 匯出
如果在Eclipse IDE 中， 在源檔案或是項目上按右鍵 , 選 Export  --->
Java --> Javadoc 就可以產生了。