@Documented的作用是使自定义注解出现在Javadoc生成的HTML文档中，仅控制注解符号（如@ApiVersion("2.0")）是否显示，不生成说明文字、不影响运行时行为，需配合正确使用、javadoc命令执行及注解实际应用才能生效。
@Documented 是 Java 提供的一个元注解，作用是标记自定义注解是否应被包含在生成的 Javadoc 文档中。它本身不生成文档内容，而是告诉 javadoc 工具：“这个注解本身，以及它所标注的元素（类、方法、字段等），请把它的存在记录到生成的 HTML 文档里”。
为什么加了 @Documented 还没出现在 Javadoc 里？
常见误解是：加了 @Documented 就自动显示注解的说明文字。其实它只控制“注解声明是否可见”，不负责渲染注解的参数值或描述。能否看到，取决于：
- 你是否用
javadoc命令正确生成文档（默认会处理 @Documented） - 你的自定义注解是否被实际用在类/方法/字段上
- Javadoc 工具版本是否支持（JDK 5+ 都支持）
- 没有额外禁用注解显示（如通过 -noqualifier 或自定义 doclet）
正确使用 @Documented 的步骤
要让自定义注解出现在 Javadoc 中，按这三步做：
- 定义注解时，在
@interface前加上 @Documented - 在类、方法等元素上使用该注解（否则文档里自然不会出现）
- 运行
javadoc生成文档（无需额外参数，默认识别 @Documented）
例如：
立即学习“Java免费学习笔记（深入）”；
deep-java-review
下载
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
@Documented
public @interface ApiVersion {
String value() default "1.0";
}然后在方法上使用：
/**
* 获取用户信息
*/
@ApiVersion("2.0")
public User getUser(int id) { ... }生成 Javadoc 后，该方法的文档页顶部会显示：@ApiVersion("2.0") —— 这就是 @Documented 起效的表现。
它和 @Retention、@Target 什么关系？
@Documented 独立于其他元注解，但常一起用：
- @Retention(RetentionPolicy.RUNTIME)：决定注解保留到运行期（方便反射读取），不影响 Javadoc
- @Target：限定注解能用在哪（比如 METHOD、TYPE），也不影响文档生成
- 三者可以共存，互不干扰；只有 @Documented 直接关联 Javadoc 输出
注意：它不显示注解的 JavaDoc 注释
即使你给自定义注解写了 Javadoc（比如对 @ApiVersion 加了 /** ... */），@Documented 不会让这些注释显示在被标注元素的文档里。它只让注解“符号”出现（如 @ApiVersion("2.0")）。若想解释注解含义，需在使用处的文档中手动说明，或在注解类的 Javadoc 中写清楚用途。
