@Documented 是一个元注解，用于使自定义注解出现在 Javadoc 生成的 HTML 文档中；它仅影响文档生成，不改变运行时或编译期行为，常与 @Retention(RetentionPolicy.RUNTIME) 配合使用。

@Documented 是 Java 中的一个元注解，它本身不改变程序逻辑，但会影响 Javadoc 文档的生成行为——具体来说，它决定**自定义注解是否会被包含在由 javadoc 工具生成的 HTML 文档中**。

让注解出现在 Javadoc 的类/方法说明里

默认情况下，JDK 不会把自定义注解（如 @Deprecated 以外的）显示在生成的 Javadoc 页面中。加上 @Documented 后，该注解就会作为“文档信息”被提取并展示在对应元素（类、方法、字段等）的 API 描述区域。

• 例如：定义一个 @ApiVersion("2.0") 注解，并用 @Documented 标记它，那么在 Javadoc 中调用该方法的页面上，就会看到一行类似 @ApiVersion("2.0") 的标注。
• 若未加 @Documented，即使代码里写了这个注解，Javadoc 输出中也不会出现它的痕迹。

只影响 Javadoc，不影响运行时或编译期

@Documented 属于 java.lang.annotation.RetentionPolicy.SOURCE 级别的元注解，但它不参与编译检查或反射读取控制。它的作用范围非常明确：

• 不影响 @Retention 或 @Target 的语义
• 不改变注解能否通过 getAnnotations() 获取（这由 @Retention(RetentionPolicy.RUNTIME) 决定）
• 唯一效果：告诉 javadoc 工具“把这个注解当成文档内容来渲染”

典型使用场景

适用于需要向 API 使用者显式传达设计意图的注解，比如：

• 版本控制类注解：@ApiVersion、@Since
• 权限或安全约束：@RequiresPermission、@RestrictedApi
• 序列化相关：@JsonIgnore（如果自己实现类似功能）
• 框架特有语义：@RestController（Spring）若希望在内部 Javadoc 中体现其角色，也可加 @Documented

和 @Retention 配合使用更常见

实际开发中，@Documented 往往与 @Retention(RetentionPolicy.RUNTIME) 一起出现，因为既要能在运行时通过反射获取，又希望在文档中可见：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface ApiVersion {
    String value();
}

这样既支持框架动态处理，也方便开发者查阅文档时快速识别接口契约。

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南