From Gossip@Openhome

Java Gossip: 要求為 API 文件的一部份 - Documented

在製作JavaDoc文件時,預設上並不會將Annotation的資料加入到文件中,例如您設計了以下的 Annotation型別:
  • Debug.java
package onlyfun.caterpillar;
public @interface Debug {}

然後將之用在以下的程式中:
  • SomeObject.java
package onlyfun.caterpillar;

public class SomeObject {
@Debug
public void doSomething() {
// ....
}
}

您可以試著產生Java Doc文件,文件中並不會有Annotation的訊息。
UnDocumented


Annotation用於為程式碼作註解,有時它包括了重要的訊息,您也許會想要使用者製作文件的同時,也一併將Annotation的訊息加入,您可以 使用java.lang.annotation.Documented,例如:
  • Debug.java
package onlyfun.caterpillar;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface Debug {}

使用java.lang.annotation.Documented時,同時的您必須使用Retention指定編譯器將訊 息加入class檔案,並可以由VM讀取,即設定RetentionPolicy為RUNTIME,接著您可以重新產生Java Doc文件,這次可以看到文件中包括了@Debug的訊息。
Documented