@Documented的作用是使自定义注解出现在Javadoc生成的HTML文档中；它仅影响文档输出，需配合@Retention(RetentionPolicy.RUNTIME)和@Target使用，不改变运行时或编译期行为。

@Documented 的作用很直接：它让自定义注解出现在 Javadoc 生成的 HTML 文档里。不加它，哪怕你在类或方法上写了 @ApiVersion("3.0") 或 @DeprecatedSince("2.5")，Javadoc 页面中也完全看不到这行标注；加上它，这些注解就会作为“文档元信息”自动显示在对应元素的说明区域。

为什么默认不显示？

Javadoc 工具默认只展示 JDK 自带的少数几个“文档化注解”，比如 @Override、@Deprecated、@SuppressWarnings。这是设计上的取舍——避免文档被大量内部或调试用注解干扰。自定义注解属于用户扩展，必须显式声明“我需要被看见”，@Documented 就是这个声明。

正确声明自定义注解的三要素

仅加 @Documented 不够，还需配合另外两个元注解才能正常工作：

• @Retention(RetentionPolicy.RUNTIME)：确保注解保留在运行时（javadoc 工具在解析 class 文件时依赖此保留策略）
• @Target：明确该注解能用在类、方法、字段等哪些位置（否则编译报错）
• @Documented：告诉 javadoc：“请把这个注解内容写进生成的 HTML 里”

生成文档时的关键操作

使用命令行或 IDE 生成 Javadoc 时，不需要额外参数来启用 @Documented 支持——只要注解本身已正确声明，javadoc 工具会自动识别并提取。

Java注释规范Skills

当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。

下载

• 命令示例：javadoc -d ./docs com.example.api（假设包路径为 com.example.api）
• IDEA 中右键 → Generate JavaDoc → 勾选目标模块即可，无需手动开启开关
• 生成后打开类页面，注解会显示在类/方法签名下方，格式如：@ApiVersion("3.0") 或 @Book(name = "Effective Java", author = "Joshua Bloch")

常见误区提醒

有些开发者误以为 @Documented 能影响运行时行为或编译检查——它只管文档输出，不参与任何逻辑判断。另外，如果注解用了 @Retention(RetentionPolicy.CLASS) 或 SOURCE，即使加了 @Documented，javadoc 也无法读取 class 文件中的注解信息，最终仍不会显示。

它不复杂但容易忽略。

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