@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 后重试，这行就会消失