要让自定义注解出现在javadoc中，需三要素齐备：@retention(retentionpolicy.runtime)、@target和@documented；注解类须有完整javadoc块注释，每个public属性用@param说明；生成时需覆盖包路径、加-private参数（如适用）、指定utf-8编码。
要让自定义注解真正出现在 Javadoc 中，光加 @Documented 不够——它只是“声明可见”，不是“自动可见”。关键在于三要素齐备、注释完整、生成过程无遗漏。
必须配齐的三个元注解
单独使用 @Documented 无法生效，它依赖另外两个元注解协同工作：
- @Retention(RetentionPolicy.RUNTIME)：javadoc 工具读取的是编译后的 class 文件，只有 RUNTIME 级别的注解才能被解析到；用 CLASS 或 SOURCE 会导致注解信息丢失，即使加了 @Documented 也显示不出来
- @Target：明确指定注解可用的位置（如 TYPE、METHOD、FIELD），否则编译会失败，自然也无法生成文档
- @Documented：告诉 javadoc：“这个注解属于公共契约，请把它和它的参数一起写进 HTML”
注解类本身要有完整 JavaDoc
只加元注解，不写文档注释，生成的页面只会显示 @ApiVersion("3.0") 这样一行代码，没有解释、没有参数说明、没有使用约束——等于白加。
- 注解类必须用
/** */块注释包裹，不能用//或/* */ - 每个 public 属性都要用
@param明确说明用途、默认值、合法取值（例如：@param value 接口版本号，格式为 x.y，如 "2.1"） - 建议加上
@since和@see，方便使用者追溯演进和关联行为
生成 Javadoc 时的关键配置
IDE 或命令行工具默认支持 @Documented，但几个细节容易导致“明明写了却看不到”：
- 确保生成命令覆盖了注解所在的包路径，例如：
javadoc -d docs com.example.annotation，漏掉包就扫描不到注解类 - 如果注解用在 private 方法上，默认 Javadoc 不输出 private 成员，需显式加
-private参数 - 中文注释必须指定编码：
-encoding UTF-8 -docencoding UTF-8，否则出现乱码，可读性直接归零 - IDEA 中右键 → Generate JavaDoc → 勾选对应模块即可，无需额外开关，但要注意“Visibility”选项是否设为 Private/Package（取决于你希望暴露的粒度）
验证是否成功生成
打开生成的 HTML 文档，检查以下位置是否出现注解信息：
- 类页顶部签名下方，应显示
@ApiVersion("3.0")或@Book(name = "Effective Java", author = "Joshua Bloch") - 方法详情区域中，该方法上方应列出所用注解，并附带你写的
@param说明 - 点击注解名跳转后，能查看到完整的 JavaDoc 页面，含摘要、参数表、作者、版本等
不复杂但容易忽略。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
