@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 使用者显式传达设计意图的注解，比如：
立即学习“Java免费学习笔记（深入）”；
- 版本控制类注解：
@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();
}
这样既支持框架动态处理，也方便开发者查阅文档时快速识别接口契约。
