@Documented的作用是使自定义注解出现在Javadoc生成的HTML文档中；它仅影响文档输出，需配合@Retention(RetentionPolicy.RUNTIME)和@Target使用，不改变运行时或编译期行为。
@Documented 的作用很直接：它让自定义注解出现在 Javadoc 生成的 HTML 文档里。不加它，哪怕你在类或方法上写了 @ApiVersion("3.0") 或 @DeprecatedSince("2.5")，Javadoc 页面中也完全看不到这行标注；加上它，这些注解就会作为“文档元信息”自动显示在对应元素的说明区域。
为什么默认不显示？
Javadoc 工具默认只展示 JDK 自带的少数几个“文档化注解”，比如 @Override、@Deprecated、@SuppressWarnings。这是设计上的取舍——避免文档被大量内部或调试用注解干扰。自定义注解属于用户扩展，必须显式声明“我需要被看见”，@Documented 就是这个声明。
正确声明自定义注解的三要素
仅加 @Documented 不够，还需配合另外两个元注解才能正常工作：
- @Retention(RetentionPolicy.RUNTIME)：确保注解保留在运行时（javadoc 工具在解析 class 文件时依赖此保留策略）
- @Target：明确该注解能用在类、方法、字段等哪些位置（否则编译报错）
- @Documented：告诉 javadoc：“请把这个注解内容写进生成的 HTML 里”
生成文档时的关键操作
使用命令行或 IDE 生成 Javadoc 时，不需要额外参数来启用 @Documented 支持——只要注解本身已正确声明，javadoc 工具会自动识别并提取。
立即学习“Java免费学习笔记（深入）”；
- 命令示例：
javadoc -d ./docs com.example.api（假设包路径为 com.example.api） - IDEA 中右键 → Generate JavaDoc → 勾选目标模块即可，无需手动开启开关
- 生成后打开类页面，注解会显示在类/方法签名下方，格式如：
@ApiVersion("3.0")或@Book(name = "Effective Java", author = "Joshua Bloch")
常见误区提醒
有些开发者误以为 @Documented 能影响运行时行为或编译检查——它只管文档输出，不参与任何逻辑判断。另外，如果注解用了 @Retention(RetentionPolicy.CLASS) 或 SOURCE，即使加了 @Documented，javadoc 也无法读取 class 文件中的注解信息，最终仍不会显示。
它不复杂但容易忽略。
