Question

我最近偶然发现了“Documented”Java Annotation的源代码。它看起来像这样：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Documented {
}

Documented中的“@Documented”的目的是什么？

Answer 1

表示默认情况下，javadoc和类似工具会记录带有类型的注释。此类型应用于注释类型的声明，其注释会影响客户端对带注释元素的使用。如果使用Documented注释类型声明，则其注释将成为带注释元素的公共API的一部分。

@Documented是一个元注释 - 它注释了另一个注释类型。当注释类型由@Documented注释时，javadoc等工具应该在代码中某处使用时包含注释。

例如，@Deprecated注释类型使用@Documented进行注释。了解某些内容是否已被弃用非常重要，因此@Deprecated被视为公共API的一部分，应该包含在文档中。

另一方面，@SuppressWarnings只是编译器的一个提示，对API不重要，因此@Documented没有注释。

@Documented注释类型也注释自己。基本上这只意味着您将在文档中看到@Documented的任何用法。这样做是为了让您可以查看是否记录了任何注释类型。