随笔- 1109 文章- 35 评论- 228 阅读- 158万

注解Documented 简介

Documented 是一个元注解（meta-annotation），它用于指示被其标记的注解类型（annotation type）应当被 javadoc 和类似的工具默认记录（或文档化）。在 Java 中，元注解是用于注解其他注解的注解。Documented 并不定义任何方法或成员变量，它是一个标记接口（marker interface），也就是说它仅仅是一个空接口，用于给被注解的注解类型添加某种语义。

类功能

Documented 注解的主要功能是告诉 javadoc 和其他文档生成工具，被其标记的注解类型应当被视为公共 API 的一部分，并且在生成的文档中应当包含这些注解类型的描述和使用方法。默认情况下，javadoc 并不包含注解类型的描述，除非这些注解类型被 @Documented 标记。

方法

Documented 注解并没有定义任何方法，它是一个空接口。然而，我们可以从它的元注解（@Documented, @Retention, @Target）中了解它的使用方式和目的。

@Documented：这个元注解本身标记了 Documented 注解。这表示当 Documented 被用于注解另一个注解类型时，javadoc 会默认包含那个注解类型的文档。但是，由于 Documented 本身就是一个元注解，所以这个 @Documented 对 Documented 注解本身并没有实际的影响。
@Retention(RetentionPolicy.RUNTIME)：这个元注解指定了 Documented 注解的生命周期。RetentionPolicy.RUNTIME 表示 Documented 注解不仅在编译时被保留在类文件中，而且在运行时可以通过反射被读取。这对于需要在运行时检查注解的工具或库来说是非常有用的。
@Target(ElementType.ANNOTATION_TYPE)：这个元注解限制了 Documented 注解的使用目标。ElementType.ANNOTATION_TYPE 表示 Documented 注解只能用于注解其他注解类型。换句话说，你不能将 Documented 注解用于类、方法、字段等其他元素。

使用示例

假设我们有一个名为 MyAnnotation 的自定义注解，并且我们希望这个注解在 javadoc 中被文档化，我们可以这样做：

package com.example.annotations;  
   
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;  
   
/**  
 * My custom annotation that should be documented by javadoc.  
 */  
@Documented  
@Retention(RetentionPolicy.RUNTIME)  
@Target(ElementType.METHOD)  
public @interface MyAnnotation {  
    String value() default "";  
}