Tiger 中的注释，第 2 部分: 定制注释

核心提示： 现在可以看出， Retention 元注释类型使用清单 11 所示的枚举值中的一个作为惟一的参数，Tiger 中的注释，第 2 部分: 定制注释(7)，可以将该元注释用于您的注释，如清单 12 所示： 清单 12. 使用 Retention 元注释 @Retention(RetentionPol

现在可以看出， Retention 元注释类型使用清单 11 所示的枚举值中的一个作为惟一的参数。可以将该元注释用于您的注释，如清单 12 所示：

清单 12. 使用 Retention 元注释
@Retention(RetentionPolicy.SOURCE)　
public　@interface　SuppressWarnings　{　
　//　annotation　type　body　
}　

如清单 12 所示，这里可以使用简写形式，因为 Retention 只有一个成员变量。如果要将保持性设为 RetentionPolicy.CLASS ，那么什么也不需要做，因为这就是默认行为。

添加公共文档

下一个元注释是 Documented 。这个元注释也非常容易理解，部分原因是 Documented 是一个标记注释。您应该还记得第 1 部分中曾经提到，标记注释没有成员变量。 Documented 表示注释应该出现在类的 Javadoc 中。在默认情况下，注释 不包括在 Javadoc 中，如果花费大量时间注释一个类、详细说明未完成的工作、正确完成了什么或者描述行为，那么您应该记住这一点。

清单 13 说明了 Documented 元注释的用法：

清单 13. 使用 Documented 元注释
package　com.oreilly.tiger.ch06;　
import　java.lang.annotation.Documented;　
import　java.lang.annotation.Retention;　
import　java.lang.annotation.RetentionPolicy;　
/**　
　*　Marker　annotation　to　indicate　that　a　method　or　class　
　*　　is　still　in　progress.　
　*/　
　　　　@Documented　
@Retention(RetentionPolicy.RUNTIME)　
public　@interface　InProgress　{　}　

Documented 的一个实用技巧是保持性策略。注意，清单 13 中规定注释的保持性（retention）是 RUNTIME ，这是使用 Documented 注释类型所 必需的。Javadoc 使用虚拟机从其类文件（而非源文件）中加载信息。确保 VM 从这些类文件中获得生成 Javadoc 所需信息的惟一方法是将保持性规定为 RetentionPolicy.RUNTIME 。这样，注释就会保留在编译后的类文件中 并且由虚拟机加载，然后 Javadoc 可以从中抽取出来添加到类的 HTML 文档中。