@Documented 是标记型元注解，仅影响 Javadoc 文档生成，使注解及其参数出现在 HTML 中；必须加在自定义注解定义上，配合标准 JavaDoc 注释和正确 javadoc 命令才能完整呈现。

@Documented 不是让注解“生效”的原理，而是告诉 Javadoc 工具：这个注解属于公共 API 的一部分，请把它连同参数一起写进生成的 HTML 文档里。它不参与编译检查、不改变运行逻辑，只影响文档输出。

---

@Documented 的作用很直接

它是一个标记型元注解（没有参数），加在自定义注解定义上，目的是让该注解在 Javadoc 中可见。
比如你写了：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ApiVersion {
    String value() default "1.0";
}

然后在方法上使用：

@ApiVersion("2.1")
public User getUserById(Long id) { ... }

生成 Javadoc 后，getUserById 方法的 HTML 页面顶部就会显示：

Annotations: @ApiVersion("2.1")

立即学习“Java免费学习笔记（深入）”；

API Documentation Generator

从代码生成全面的 API 文档，提取 Express、FastAPI、Django、Rails等框架的端点、参数、响应模式及示例。

下载

没加 @Documented，这一行就不会出现。

---

必须配合的三个关键点

• 必须加在注解定义上
  @Documented 只能用在 @interface 前面，不能写在使用处（如方法上），否则无效。

• 注解类本身要有标准 JavaDoc 注释
  仅加 @Documented，文档里只会显示 @ApiVersion("2.1") 这一行代码。要说明它是干啥的，得在注解接口上方写：

  /**
   * 标明该接口支持的最低 API 版本，用于客户端兼容性控制。
   * @param value 版本号，格式为 x.y，如 "2.1"
   * @since 1.0
   */
  @Documented
  @Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.METHOD)
  public @interface ApiVersion {
      String value() default "1.0";
  }

  这样生成的注解类型页面（如 ApiVersion.html）才会包含这段说明。

• 生成文档时要扫到注解所在包，并处理编码

  • 命令行执行 javadoc 时，需显式指定包路径：
    javadoc -encoding UTF-8 -docencoding UTF-8 -d docs com.example.annotation
  • 如果注解用在 private 方法上，默认不生成，要加 -private 参数。
  • IDEA 中右键 → Generate JavaDoc → 确保勾选对应模块，“Visibility”设为 Package 或 Private（按需）。

---

它不是万能的，但很关键

• @Documented 不负责解释方法参数、返回值或异常，那些仍需手动写 @param、@return、@throws。
• 它不影响 IDE 悬停提示——那是编辑器解析源码的结果，和 Javadoc 无关。
• 它不替代 Swagger 或 SpringDoc，而是互补：前者说明“注解本身是啥”，后者说明“接口怎么调”。

不复杂但容易忽略。