Javadoc注釋标簽文法

【作者：meganlee】 核心提示：javadoc可以根據項目代碼的注釋（當然是規範化的）自動生成HTML格式的API文檔。

javadoc可以根據項目代碼的注釋（當然是規範化的）自動生成HTML格式的API文檔。

三種注釋類型（注釋必須緊貼着注釋體，不然javadoc會忽略）：

類注釋

變量注釋

方法注釋

書寫格式：

參數說明：

@see 生成文檔中的“參見xx 的條目”的超連結，後邊可以加上：“類名”、“完整類名”、“完整類名#方法”。可用于：類、方法、變量注釋。

@param 參數的說明。可用于：方法注釋。

@return 傳回值的說明。可用于：方法注釋。

@exception 可能抛出異常的說明。可用于：方法注釋。

@version 版本資訊。可用于：類注釋。

@author 作者名。可用于：類注釋。

@deprecated 對類或方法的說明 該類或方法不建議使用,引起不推薦使用的警告

@note  表示注解，暴露給源碼閱讀者的文檔

@remark 表示評論，暴露給客戶程式員的文檔

@since 表示從那個版本起開始有了這個函數

@see  表示交叉參考

javadoc指令：

javadoc [options] [packagenames] [sourcefiles]

-public 僅顯示 public 類和成員

-protected 顯示 protected/public 類和成員 (預設)

-package 顯示 package/protected/public 類和成員

-private 顯示所有類和成員

-d  輸出檔案的目标目錄

-version 包含 @version 段

-author 包含 @author 段

-splitindex 将索引分為每個字母對應一個檔案

@interface

它用于定義新的注釋類型（annotation type）。建立一個注釋類型看起來和定義一Interface 沒有什麼兩樣，

MyTag.java用于建立一個使用者自定義标簽，代碼如下，

＝===============================================================================

package tiger.annotation;

public @interface MyTag { }

定義了一個tag之後，我們就可以在任何java檔案中使用這個tag了，

import tiger.annotation.MyTag;

public class TagTest{

    @MyTag

    public void testTag(){

    }

}

===============================================================================

注釋類型還可以有成員變量，

==============================================================================

package tiger.annotation;

public @interface MyTag {

    String name();

    int age();

}

=============================================================================

然後我們可以這麼使用這個标簽，

    @MyTag(name="MyTag",age=1)

    public void testTag(){

    }

    使用标簽最終是為了幫助開發人員提取注釋資訊，然後根據不同需求做進一步處理，下面我們來看看如何擷取注釋資訊。

=============================================================================

import java.lang.annotation.Annotation;

import tiger.annotation.MyTag;

public class TagTest{

    @MyTag(name="MyTag",age=1)

    public void test(){

    }

    public static void main(String[] args){

        TagTest tt = new TagTest();

        try {

            Annotation[] annotation =tt.getClass().getMethod("test").getAnnotations();

            for (Annotation tag :annotation)  {            

              System.out.println("Tag is:" + tag);

              System.out.println("tag.name()" + ((MyTag)tag).name());

              System.out.println("tag.age()" + ((MyTag)(tag)).age());

             }

         } catch(NoSuchMethodException e) {

             e.printStackTrace();

         }

    }

}

===============================================================================

     需要注意的一點是，在執行這段代碼之前我們還有一點小工作要做，還需要給我們的自定義标簽MyTag加上一個說明标簽，@ Retention, 表明注釋資訊将可以在運作時刻通過反射機制得到。如果不加入這個标簽，上面的代碼将沒有任何輸出。修改以後的MyTag如下，

================================================================================

@Retention(RetentionPolicy.RUNTIME)

public @interface MyTag {

    String name();

    int age();

}

================================================================================

然後我們執行TagTest可以得到輸出如下，

Tag is:@tiger.annotation.MyTag(name=MyTag, age=1)

tag.name()MyTag

tag.age()1

好了，Tiger新的注釋文法基本用法就這麼簡單，基本用法雖然簡單，但是擷取注釋資訊之後如何處理确很值得推敲，我們可以用他們來做一些文法檢查，檔案相關性檢查，進行各種統計等等