要让自定义注解出现在 javadoc 中，必须同时使用 @documented、@retention(retentionpolicy.runtime) 和 @target；@documented 仅控制注解是否显示在生成的 html 文档中，不影響运行时行为或 ide 提示。
要让自定义注解出现在 Javadoc 生成的 HTML 文档中，必须在注解定义上显式添加 @Documented。它不处理普通注释（如 // 或 /** */），只控制该注解本身是否作为元数据被展示在 API 文档里。
@Documented 的核心作用
@Documented 是一个元注解，没有参数，也不改变运行时行为或编译检查。它的唯一职责是告诉 javadoc 工具：“这个注解属于公共 API 的一部分，请把它列在类、方法或字段的文档摘要中。”
- JDK 自带的
@Deprecated、@Override默认已带@Documented，所以天然可见 - 自定义注解默认不会出现在文档里，哪怕用了
@Retention(RetentionPolicy.RUNTIME)也不行 - IDE 中的悬浮提示是否显示注解，和
@Documented无关，取决于 IDE 对元注解的支持程度
必须搭配的两个元注解
单加 @Documented 不足以让注解正常工作，还需配合以下两个元注解声明：
-
@Retention(RetentionPolicy.RUNTIME)：确保注解信息保留在 class 文件中，javadoc 才能读取到 -
@Target({ElementType.TYPE, ElementType.METHOD, ...})：明确注解可用的位置，否则编译会报错
三者缺一不可。例如：
@Documented<br>@Retention(RetentionPolicy.RUNTIME)<br>@Target({ElementType.TYPE, ElementType.METHOD})<br>public @interface ApiVersion {<br> int value() default 1;<br>}
验证是否生效的实操步骤
生成 Javadoc 后直接查看 HTML 页面即可确认效果：
- 在类或方法上使用该注解，如
@ApiVersion(2) public class UserService { } - 执行命令：
javadoc -d docs UserService.java（或指定包路径） - 打开生成的
docs/UserService.html，在类签名下方查找类似Annotations: @ApiVersion(2)的说明行 - 移除
@Documented后重试，该行将消失
提升文档可读性的建议
让使用者真正理解注解含义，不能只靠 @Documented 显示符号，还需主动补充说明：
- 在注解接口上方写标准文档注释，例如：
/** 标记该组件支持的最低 API 版本，影响客户端兼容性 */ - 若注解含多个属性，建议在文档注释中说明各参数用途
- 配合
@param、@return等标签完善被注解元素本身的文档，@Documented不会自动补全这些内容
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
