@Documented 使自定义注解在 Javadoc 生成的 HTML 文档中可见，需配合 @Retention(RUNTIME) 和 @Target 使用，且注解类自身须有完整 JavaDoc；仅影响文档输出，不改变运行逻辑。

@Documented 的作用很明确：让自定义注解在用 javadoc 工具生成的 HTML 文档中可见。它不改变程序运行逻辑，只影响文档输出——加了它，你在类、方法或字段上写的 @ApiVersion("3.0") 或 @Column(name = "user_id") 就会原样显示在对应 API 页面里；不加，javadoc 就完全忽略这个注解。

必须配合另外两个元注解才能生效

单独加 @Documented 是无效的，它需要和以下两个元注解协同工作：

• @Retention(RetentionPolicy.RUNTIME)：确保注解信息保留在编译后的 class 文件中，javadoc 工具才能读取到它
• @Target（如 ElementType.METHOD）：声明注解可用的位置，否则编译器直接报错，根本走不到生成文档这步

注解类自身要有完整 JavaDoc

就算加了 @Documented，如果注解类本身没写说明，生成的文档里只会显示 @MyAnnotation 几个字，用户不知道它是干啥的。正确做法是：

Java调试

通过 JDWP 实现 Java 远程调试：连接远程 JVM、设置断点、单步执行代码、查看变量值、获取调用栈。适用于需要调试远程 Java 应用、排查运行时状态、追踪代码执行流程的场景。 术语注解 JDWP：Java Debug Wire Protocol，Java 调试有线协议（Java 远程调试底层通信协议） remote JVM：远程 Java 虚拟机 step through code：代码单步调试（步入 / 步过 / 步出调试） inspect variables：变量查看 / 变量检视 stac

下载

• 用 /** */ 多行注释写 JavaDoc，不能用 // 或 /* */
• 每个 public 属性都用 @param 描述用途、默认值、取值范围
• 补充 @since、@see 等，比如 “仅用于 REST 接口版本控制”

生成文档时要注意可见范围和编码

javadoc 默认只处理 public 和 protected 成员。如果你把注解用在 private 方法上，又没加 -private 参数，它就不会出现在文档里。另外：

• 命令行生成建议加上 -encoding UTF-8 -docencoding UTF-8，避免中文乱码
• IDEA 中右键 → Generate JavaDoc → 勾选对应模块即可，不用额外开关
• 确保 javadoc 命令扫描到了注解所在的包，例如：javadoc -package com.example.annotation

它不是万能的，但很关键

@Documented 只管文档展示，不影响运行时行为，也不参与编译检查。如果注解用了 @Retention(RetentionPolicy.SOURCE)，哪怕加了 @Documented，class 文件里没有它，javadoc 也抓不到。它不复杂但容易忽略。

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南