在Java代码库的开发过程中，公共API的清晰度直接影响其他开发者的使用体验。@Documented是Java标准库中提供的元注解之一，它的核心作用是标记其他注解是否会被包含在Javadoc生成的文档中，这对公共API的文档完整性有着重要影响。
@Documented的基本定义
@Documented属于Java的元注解，即用于修饰其他注解的注解，它的源码定义非常简单，本身没有任何成员变量，仅作为一个标记型注解存在。它的作用是告诉Javadoc工具，被它修饰的注解需要被记录到生成的API文档中。
如果一个自定义注解没有被@Documented修饰，那么即使这个注解被用在公共类、公共方法或者公共字段上，生成的Javadoc文档中也不会体现这个注解的存在。
未使用@Documented的自定义注解示例
我们先定义一个没有添加@Documented的自定义注解，然后将其用在公共API的方法上，观察生成的文档效果。
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
// 没有使用@Documented修饰的自定义注解
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface NotDocumentedAnnotation {
String value() default "";
}
接下来在公共API的方法上使用这个注解：
public class UserApi {
// 使用未加@Documented的注解
@NotDocumentedAnnotation("用户ID不能为空")
public void getUserById(String userId) {
// 方法逻辑
}
}
此时使用Javadoc工具生成文档后，getUserById方法的说明中不会出现@NotDocumentedAnnotation相关的任何信息，使用者无法从文档中得知这个方法有对应的注解约束。
使用@Documented的自定义注解示例
我们修改自定义注解的定义，添加@Documented修饰，再观察文档的变化：
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;
// 添加@Documented修饰的自定义注解
@Documented
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface DocumentedAnnotation {
String value() default "";
}
同样在公共API的方法上使用这个注解：
public class UserApi {
// 使用加了@Documented的注解
@DocumentedAnnotation("用户ID不能为空")
public void getUserById(String userId) {
// 方法逻辑
}
}
重新生成Javadoc文档后，getUserById方法的说明中会明确展示@DocumentedAnnotation注解以及它的属性值，使用者可以直接从文档中了解到这个方法的额外约束信息。
@Documented提升公共API可读性的具体场景
1. 标记API的约束条件
很多公共API会有参数校验、权限要求等约束，通过带@Documented的注解可以将这些约束直接体现在文档中，避免使用者需要查看源码才能知道规则。
@Documented
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface NotNull {
String message() default "参数不能为空";
}
public class OrderApi {
public void createOrder(@NotNull(message = "订单信息不能为空") Order order) {
// 创建订单逻辑
}
}
生成的文档中会明确显示createOrder方法的order参数需要标注@NotNull，使用者可以提前知晓参数校验规则。
2. 说明API的废弃原因
当公共API需要废弃时，使用带@Documented的自定义废弃注解，可以在文档中说明废弃原因和替代方案，比默认的@Deprecated注解传递更多信息。
@Documented
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface DeprecatedApi {
String reason() default "";
String alternative() default "";
}
public class OldApi {
@DeprecatedApi(
reason = "性能较低，不再维护",
alternative = "请使用NewApi中的queryData方法"
)
public void oldQuery() {
// 旧查询逻辑
}
}
3. 标注API的适用场景
对于有特殊适用场景的API，可以通过带@Documented的注解标注适用环境、版本要求等信息，帮助使用者快速判断是否适合使用当前API。
使用@Documented的注意事项
- @Documented仅对Javadoc生成的文档生效，不会影响代码运行时的注解获取逻辑。
- 只有保留策略为RetentionPolicy.RUNTIME或者RetentionPolicy.CLASS的注解，使用@Documented才有意义，因为RetentionPolicy.SOURCE的注解在编译后就会被丢弃，无法被文档工具读取。
- 不要过度使用@Documented，仅对公共API相关的注解添加该修饰，避免文档中出现过多无用的注解信息，反而影响可读性。
合理使用@Documented可以让公共API的文档信息更加完整，减少使用者的理解成本，是提升代码库易用性的重要手段之一。在开发公共API时，建议对需要暴露给使用者的注解统一添加@Documented修饰，保证文档的准确性。
@DocumentedJava注解public_API代码可读性修改时间：2026-06-17 21:57:33