@Documented的作用是让自定义注解出现在Javadoc生成的HTML文档中，仅作为文档元信息呈现，不影响代码逻辑；需配合@Retention(RUNTIME)和@Target使用，且注解类须有完整Javadoc注释。
@Documented 的作用很直接：让自定义注解出现在 Javadoc 生成的 HTML 文档中。它不改变代码逻辑，也不影响编译或运行时行为，只负责把注解作为“文档元信息”呈现给使用者。
让注解在 API 文档里真正可见
默认情况下，Javadoc 只显示 JDK 自带的少数几个注解（如 @Deprecated、@Override）。自定义注解即使被大量使用，也不会自动出现在文档里——除非显式加上 @Documented。
- 加了 @Documented：在类/方法签名下方会显示类似 @ApiVersion("3.0") 或 @Book(name = "Effective Java") 的说明行
- 没加 @Documented：文档中完全看不到该注解，使用者只能翻源码或查手册
- 这个可见性对公共 API 尤其关键——调用方一眼就能确认接口是否受版本控制、是否已弃用、是否需鉴权等
必须配合的两个元注解
@Documented 单独存在是无效的。它需要和另外两个元注解协同工作，才能确保注解既可被 javadoc 工具读取，又能在合理位置使用：
- @Retention(RetentionPolicy.RUNTIME)：javadoc 解析的是 class 文件，只有 RUNTIME 级别的注解才能被提取；用 CLASS 或 SOURCE 会导致注解丢失
- @Target({ElementType.TYPE, ElementType.METHOD, ...})：明确限定注解可用范围，避免误用；编译器会据此检查，缺失则报错
生成文档时的关键细节
只要注解声明正确，javadoc 工具会自动识别 @Documented，无需额外开关。但实际集成中容易忽略以下几点：
立即学习“Java免费学习笔记（深入）”；
- 命令行执行时建议加上 -encoding UTF-8 -docencoding UTF-8，否则中文注释可能乱码
- IDEA 中右键 → Generate JavaDoc → 勾选对应模块即可，但需确认“Visibility”选项包含 PACKAGE 或 PUBLIC（private 成员默认不生成）
- 注解类自身必须有完整 Javadoc 注释（/** ... */），且每个 public 属性都用 @param 说明用途，否则文档里只显示注解名，没有解释
和团队协作流程结合更有效
@Documented 的价值在规模化协作中才会充分释放：
- 把“所有对外注解必须含 @Documented + 完整 JavaDoc”写入编码规范，并通过 CI 检查（例如用 Checkstyle 或自定义脚本扫描 annotation 类）
- 将生成的 JavaDoc 部署为静态站点，与 Swagger 页面、README 并列，构成统一开发者门户
- IDE 悬停提示会自动展示带 @Documented 的注解说明，开发时无需切出上下文就能理解语义
