@Documented需与@Retention(RUNTIME)和@Target配合使用，且注解类须含完整JavaDoc（含@param、@since等），javadoc命令需正确配置包路径和可见性参数，才能在HTML文档中显示注解及其说明。
@Documented 是让自定义注解真正“被看见”的关键一环，但它不是开关，而是一份文档契约的声明——只有当它和规范注释、正确元注解、合理构建流程配合时，框架的 API 文档才能自动同步、清晰可读。
注解本身必须带完整 JavaDoc
仅加 @Documented 不会产生说明文字。注解类必须用 /** */ 块注释包裹，并对每个 public 属性明确说明：
- 用 @param 描述参数用途、默认值、取值范围（如 @param value 接口支持的最小版本号，格式为 x.y，默认 1.0）
- 用 @since 标明首次引入版本
- 用 @see 关联相关注解或行为约束（如 @see @ApiStable）
- 正文需直述语义（如 “标记该服务接口兼容指定版本的客户端请求”）
三个元注解缺一不可
@Documented 单独存在无效，必须与以下两个元注解共存：
- @Retention(RetentionPolicy.RUNTIME)：确保编译后注解保留在 class 文件中，javadoc 工具才能读取
- @Target({ElementType.TYPE, ElementType.METHOD})：明确注解可用位置，否则编译失败，自然无法生成文档
- @Documented：声明该注解属于公共契约，应出现在最终 HTML 文档中
生成文档时要覆盖真实使用场景
Javadoc 默认只处理 public 成员，且依赖路径和编码设置：
立即学习“Java免费学习笔记（深入）”；
- 命令行执行时需显式包含注解所在包，例如：javadoc -d docs -encoding UTF-8 -docencoding UTF-8 com.example.annotation com.example.api
- 若注解用于 private 方法或字段，需加 -private 参数，否则不扫描
- IDE 中生成时，检查 “Visibility” 设置是否匹配实际可见性需求（Package 或 Private）
验证是否生效的直观方式
打开生成的 HTML 文档，查看被注解的类或方法页面：
- 签名下方应出现类似 @ApiVersion(2) 或 @Retryable(maxAttempts = 3) 的标注行
- 点击该注解名称，应跳转至其定义页，并显示完整的 JavaDoc 内容（含 @param、@since 等）
- 对比移除 @Documented 后重新生成的结果——那一行将彻底消失
