Java 註釋技巧【總結的不錯】

Java 註釋技巧
    在最初學習Android時候使用了Eclips IDE工具，編寫java程序時，老是要添加一些註釋，用以說明某段代碼的做用，因爲是從C過分來的，也沒有太在乎java的註釋有何不一樣，將鼠標移動到Android sdk 提供的類、方法、屬性上時總會有提示信息，並且彈出的提示信息就是代碼註釋，不一樣的是有一些特殊的符號，隨着工程代碼量的不斷增長，文檔註釋的重要性日漸凸顯，索性學習下Java的註釋方法，讓本身的代碼變得更規範化一些。

JavaDoc工具
    Java 有三種註釋語句：
    1.//用於單行註釋。  
    2./*...*/用於多行註釋，從/*開始，到*/結束，不能嵌套。  
    3./**...*/則是爲支持 jdk 工具 javadoc.exe 而特有的註釋語句。

    當你在代碼中填寫好註釋後，就可使用JavaDoc工具提取程序中文檔註釋生成API文檔，Javadoc 工具能從 java 源文件中讀取第三種註釋，並能識別註釋中用@標識的一些特殊變量，製做成 Html 格式的類說明文檔。javadoc 不但能對一個 java 源文件生成註釋文檔，並且能對目錄和包生成交叉連接的 html 格式的類說明文檔，十分方便。

    經常使用的Javadoc標記以下：
    @author         指定Java程序的做者
    @version        指定源文件版本
    @parameter      參數名及其意義
    @return         返回值
    @throws         異常類及拋出條件
    @deprecated     引發不推薦使用的警告（標識一個方法已經不推薦使用了）
    @see            「參見」，指定交叉參考的內容
    @since          表示從那個版本起開始有了這個函數 
    @note           表示註解，暴露給源碼閱讀者的文檔 
    {@value}        當對常量進行註釋時，若是想將其值包含在文檔中，則經過該標籤來引用常量的值。
    {@link包.類#成員} 連接到某個特定的成員對應的文檔中。
    
    PS:只有/**...*/的註釋語句中的內容才能被javadoc工具支持，因此javadoc的標記只能放在/**...*/註釋中。

Javadoc與html
    因爲Javadoc生成的是html的樣式，因此在文檔註釋中支持部分html的標籤，下面是在使用文檔註釋經常使用的標籤：

    段落級標籤
    1)段落: <p>用於標記段落的開始，段落結束</p>
    
    2)換行: <br>
    
    3)<pre>預格式化標籤: 
    <pre>  </pre> 此標籤用於顯示預先已定義好格式的文本。當文本顯示在瀏覽器中時，會遵循已在HTML源文檔中定義的格式。

    文本格式化標籤
    1)<b>標籤
    <b>該文本將以粗體顯示</b>
    
    2)<i>標籤
    <i>該文本將以斜體顯示</i>
    
    3)<sub>標籤
    _{該文本的顯示高度將低於先後的文本}
    
    4)<sup>標籤
    ^{該文本的顯示高度將高於周圍的文本}
    
    5)<blockquote>標籤
    定義長的引用，<blockquote> </<blockquote>所包含的文字會被總體分離出來，讓這段文字與周圍文字造成對比，有縮進效果。

    5)<hr>
    <hr>用於定義水平分隔線
   

    列表標籤
    <ul>  無序列表 
    <ol>  有序列表 
    <li>  列表項目的標籤

    連接標籤
    1)<a>  定義連接 href  指定連接地址
     <a href= "http://blog.csdn.net/jack_chen_00">博客地址</a>

文檔註釋範例
    
/**
 * <a href= "<a target=_blank href="http://blog.csdn.net/jack_chen_00">http://blog.csdn.net/jack_chen_00</a>">博客地址</a>
 * @author Jack·chen 
 */
public static class Person{
 
 /**男性，值爲<a target=_blank href="mailto:{@value}*/">{@value}*/</a> 
 public static final int MALE = 1;
 /**女性，值爲<a target=_blank href="mailto:{@value}*/">{@value}*/</a>
 public static final int FEMALE = 2;</p><p> /**
  * use to store person name 
  */
 protected String mName;
 /**
  * use to store second name of person
  * @see #mName
  */
 protected String mSecondName;
 
 /**/
 protected int mAge;</p><p> /**
  * Constructor that is called when inflating a view from XML. 
  * 
  * The class will be created after all children have been added.
  * added.
  * @version 1.0
  * @param mName name of person
  * @param mSndName  second name of person
  * @param mAge age of person
  */
 public Person(String mName,String mSndName, int mAge) {
  super();
  this.mName = mName;
  this.mSecondName = mSndName;
  this.mAge = mAge;
 }
 
 /**
  * ^Constructorthat is called when inflating a view from XML.
     * 
  * <ul>
  * <li>The view receives a hover event with action <a target=_blank href="mailto:{@link">{@link</a> MotionEvent#ACTION_HOVER_ENTER}
  * when the pointer enters the bounds of the view.</li>
  * <li>The view receives a hover event with action <a target=_blank href="mailto:{@link">{@link</a> MotionEvent#ACTION_HOVER_MOVE}
  * when the pointer has already entered the bounds of the view and has moved.</li>
  * <li>The view receives a hover event with action <a target=_blank href="mailto:{@link">{@link</a> MotionEvent#ACTION_HOVER_EXIT}
  * when the pointer has exited the bounds of the view or when the pointer is
  * about to go down due to a button click, tap, or similar user action that
  * causes the view to be touched.</li>
  * </ul>
  * 
  * <pre> public boolean onGenericMotionEvent(MotionEvent event) {
     *     if ((event.getSource() & InputDevice.SOURCE_CLASS_JOYSTICK) != 0) {
     *         if (event.getAction() == MotionEvent.ACTION_MOVE) {
     *             // process the joystick movement...
     *             return true;
     *         }
     *     }
     *     return super.onGenericMotionEvent(event);
     * }</pre>
     * 
  * <p>
  * The class will be created after all children have been added.
  * added.
  * @deprecated use <a target=_blank href="mailto:{@link">{@link</a> #Person(String,String,int)} instead
  * @version 1.0
  * @see Monkey
  * @param mName name of person
  * @param mAge age of person
  */
 public Person(String mName, int mAge) {
  super();
  this.mName = mName;
  this.mAge = mAge;
 }
 
}
Annotation
    從JDK 1.5開始，Java增長了對元數據(MeteData)的支持，也就是annotation(註釋)，這種Annotation與前面講的註釋有必定的卻別，它是代碼一種特殊的標記，這些標記能夠在編譯、類加載、運行時被讀取，並執行相應的處理。經過Annotation，程序員能夠在不更改源碼的狀況下嵌入一些補充信息，訪問和處理Annotation的工具統稱爲APT(Annotation Processing Tool)。代碼分析工具、開發工具能夠利用這些補充信息進行驗證，好比Eclips能夠根據@Override檢查複寫方法的正確性。   

    標準的Annotation
    先看下Java提供的3個最基本的Annotation的用法：
    @Deprecated
    可做用於方法、類、接口等，它的做用於文檔中註釋中的@deprecated基本相同，是告訴編譯器此方法、類等已經不建議使用了，以便在編程時給出警告。
    
    @Override
    只能做用於方法，用於指出該方法是重載父類的方法，它的做用是告訴編譯器檢查這個方法的語法是否正確，避免犯一些方法名稱寫錯的低級錯誤。
    
    @SuppressWarnings
    用於消除編譯器警告，在某些狀況下編譯警告是被容許或者合法，在這種狀況下就可使用@SuppressWarnings消除編譯器警告
    
    若是你是用IDE工具Eclips開發Android 應用程序，你會發現上面提到的三個Annotation不須要手動添加，Eclips會自動提示你警告的緣由以及解決辦法，並自動幫你生成合適的Annotation補充信息，基本不須要程序員手動添加。
   

    自定義Annotation
    除了標準的Annotation，程序員還能夠編寫自定義的Annotation，自定義的Annotation可用於debug和編寫一些測試程序。
    java中自定義annotation須要@interface關鍵字和用到幾個內置annotation。用到的元註解有@Target, @Retention, @Documented, @Inherited ，用途以下：
    @Target 表示該註解用於什麼地方，可能的 ElemenetType 參數包括： 
        ElemenetType.CONSTRUCTOR 構造器聲明 
        ElemenetType.FIELD 域聲明（包括 enum 實例） 
        ElemenetType.LOCAL_VARIABLE 局部變量聲明 
        ElemenetType.METHOD 方法聲明 
        ElemenetType.PACKAGE 包聲明 
        ElemenetType.PARAMETER 參數聲明 
        ElemenetType.TYPE 類，接口（包括註解類型）或enum聲明 
         
    @Retention 表示在什麼級別保存該註解信息。可選的 RetentionPolicy 參數包括： 
        RetentionPolicy.SOURCE 註解將被編譯器丟棄 
        RetentionPolicy.CLASS 註解在class文件中可用，但會被VM丟棄 
        RetentionPolicy.RUNTIME VM將在運行期也保留註釋，所以能夠經過反射機制讀取註解的信息。 
         
    @Documented 將此註解包含在 javadoc 中 
     
    @Inherited 容許子類繼承父類中的註解

   

package javatest;   import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; import java.lang.reflect.Method; import java.util.HashSet; import java.util.Set;   public class JavaProject {           @Target(ElementType.TYPE)     @Retention(RetentionPolicy.RUNTIME)     @Documented     public @interface Description {         String value() default "no description";     }       @Target(ElementType.METHOD)     @Retention(RetentionPolicy.RUNTIME)     @Documented     public @interface Name {         String originate();         String community();     }       @Description("Mantis,Debug eye")     public static class JavaAnnotation {         @Name(originate = "創始人:jack", community = "sunplus")         public String getDebugProjectName() {             return "Mantis";         }         @Name(originate = "創始人:清風道人", community = "suncompany")         public String getStateName() {             return "debuging";         }     }         public static void main(String[] args) {         Class test = JavaAnnotation.class;         Method[] methods = test.getMethods();         boolean flag = test.isAnnotationPresent(Description.class);         if (flag) {             Description des = (Description) test.getAnnotation(Description.class);             System.out.println("描述:" + des.value());             System.out.println("-----------------");         }         Set<Method> set = new HashSet<Method>();         for (int i = 0; i < methods.length; i++) {             boolean otherflag = methods[i].isAnnotationPresent(Name.class);             if (otherflag) {                 set.add(methods[i]);             }         }         for (Method method : set) {             Name name = method.getAnnotation(Name.class);             System.out.println(name.originate());             System.out.println("建立的社區:" + name.community());         }     }   }