要让自定义注解出现在 JavaDoc 中，需同时满足：①用 @Documented 修饰注解；②指定 @Retention(RetentionPolicy.RUNTIME 或 CLASS)；③正确声明 @Target；④在注解及使用处添加 Javadoc 注释。
要让自定义注解出现在生成的 JavaDoc 中，关键不是简单加上 @Documented，而是它必须配合正确的注解声明方式和 Javadoc 工具链使用。
什么是 @Documented？
@Documented 是一个元注解，作用是告诉 Javadoc 工具：把这个注解本身（而不是仅其作用）也纳入生成的文档。它不会自动让注解的参数或用法说明出现，只决定“该注解是否应被记录在类/方法的文档里”。比如你给某个方法加了 @ApiStatus.Stable，加上 @Documented 后，Javadoc 页面中这个方法的描述下方才会显示 “@ApiStatus.Stable” 这行字。
正确声明一个可文档化的注解
声明时需满足三点：
- 用
@Documented修饰你的自定义注解类型 - 指定合适的
@Retention(RetentionPolicy.RUNTIME)或CLASS（Javadoc 需要能在编译后读取到该注解） - 明确
@Target，比如ElementType.METHOD、ElementType.TYPE等，否则编译器可能拒绝使用
示例：
立即学习“Java免费学习笔记（深入）”；
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface ApiVersion {
String value() default "1.0";
}让注解用途真正体现在 Javadoc 中
@Documented 只控制“是否显示注解标记”，不控制“怎么写说明”。要让使用者清楚怎么用，还得靠 Javadoc 注释本身：
- 在注解定义上方写标准 Javadoc，说明用途、参数含义、典型场景
- 在被标注的类、方法等元素上，同样写 Javadoc，必要时解释为何此处用了该注解
- 运行
javadoc命令时确保没加-noqualifier或过滤掉注解的选项
例如，在 @ApiVersion 上写：
/**
* 标记 API 的版本号，用于兼容性管理。
*
* @see ApiStatus
* @since 2.1
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface ApiVersion {
/**
* 主版本号，格式如 "1.0"、"2.1-beta"。
*/
String value() default "1.0";
}常见误区与验证方式
很多人加了 @Documented 却没看到效果，问题通常出在：
- Javadoc 没重新生成（尤其 IDE 中未触发完整 javadoc 构建）
- 注解用在了
@Target不允许的位置，导致实际未生效 - 使用的 Javadoc 工具版本过低（Java 5+ 支持，但旧插件可能忽略）
- 注解虽被标记，但目标元素本身没写 Javadoc，导致页面空白——
@Documented不会自动补说明
验证是否生效：生成 Javadoc 后，打开对应类或方法的 HTML 页面，搜索注解名，看是否出现在“Annotations”栏目或签名下方。
