@documented 使自定义注解出现在 javadoc 文档中，需配合 @retention(runtime) 和 @target 使用，注解类须有完整 javadoc 注释，生成时需正确配置包路径、可见性及编码。
@Documented 的作用很明确：让自定义注解出现在 Javadoc 生成的 HTML 文档里。它不改变代码行为，也不参与编译或运行逻辑，只负责把注解本身作为“元数据说明”展示出来。
必须配齐的三个元注解
单独加 @Documented 没用，它需要和另外两个元注解协同工作：
- @Retention(RetentionPolicy.RUNTIME)：javadoc 工具解析的是 class 文件，只有 RUNTIME 级别的注解才能被读取到；用 SOURCE 或 CLASS 会导致信息丢失
- @Target：明确注解能用在哪些位置（如 TYPE、METHOD、FIELD），否则编译失败，自然无法生成文档
- @Documented：告诉 javadoc：“这个注解属于公共契约，请把它连同参数一起写进文档”
注解类本身要有完整 JavaDoc
光有元注解，不写文档注释，生成的页面只会显示 @ApiVersion("2.0") 这样一行代码，没有解释也没有约束说明。
- 注解定义必须用 /** */ 块注释包裹，不能用 // 或 /* */
- 每个 public 属性都要用 @param 描述用途、默认值、合法范围（例如：@param value 接口版本号，格式为 x.y，如 "2.1"）
- 建议补充 @since 和 @see，方便使用者理解演进路径和关联行为
生成文档时的关键配置
Javadoc 工具默认支持 @Documented，但几个细节常导致“写了却看不到”：
- 确保命令覆盖注解所在包，例如：javadoc -d docs com.example.annotation，漏掉包就扫描不到
- 如果注解用在 private 方法上，需显式加 -private 参数，否则默认不输出
- 中文注释必须指定编码：-encoding UTF-8 -docencoding UTF-8，否则乱码
- IDEA 中右键 → Generate JavaDoc → 勾选对应模块即可，但要注意 “Visibility” 设置是否匹配你的暴露粒度
验证是否生效的直接方式
最可靠的方法是动手生成一次文档并查看结果：
- 写一个带 @Documented 的注解，比如 @ApiVersion，并在某个类或方法上使用它
- 执行 javadoc -d docs YourClass.java
- 打开生成的 HTML 页面，在类或方法签名下方，应看到类似 @ApiVersion(2) 的说明行
- 去掉 @Documented 后重试，这行就会消失
