Java自定义注解的文档化：@Documented实战应用-java教程-PHP中文网

@documented的作用是让自定义注解出现在javadoc中，需配合@retention(retentionpolicy.runtime)和@target声明，三者缺一不可；它仅影响文档生成，不改变代码行为或运行时逻辑。

java自定义注解的文档化：@documented实战应用

@Documented 的作用很明确：让自定义注解出现在 Javadoc 生成的 HTML 文档中。它不改变代码行为，也不参与编译或运行时逻辑，只负责“被看见”——只要加了它，且其他条件满足，你在类、方法上写的 @ApiVersion("3.0") 或 @Validated 就会原样显示在 API 文档里。

为什么加了 @Documented 还是没显示？

常见原因不是漏写 @Documented，而是配套元注解缺失或配置不当：

@Retention 必须设为 RetentionPolicy.RUNTIME；若用 CLASS 或 SOURCE，javadoc 工具读不到注解信息，自然无法渲染
@Target 必须声明，比如 @Target({ElementType.TYPE, ElementType.METHOD})；否则编译直接报错，根本走不到文档生成环节
注解本身未被实际使用——@Documented 只影响“被使用的注解”的文档呈现，不作用于注解定义页面

正确声明一个可文档化的自定义注解

三要素缺一不可，顺序不重要，但建议按习惯排列：

deep-java-review

Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...

下载

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface ApiVersion {
    String value();
}

这样定义后，在 Controller 类上写 @ApiVersion("2.1")，生成 Javadoc 时，该注解就会出现在类签名下方，格式清晰，如：@ApiVersion("2.1")

Javadoc 生成时无需额外配置

只要源码中注解已正确定义，生成过程全自动识别：

命令行执行：javadoc -d docs src/main/java/com/example/**，无需加 -doclet 或开关参数
IDEA 中右键模块 → Generate JavaDoc → 选中范围和输出路径即可
生成后打开对应类的 HTML 页面，注解会显示在元素签名正下方，字体略小、带等宽样式，与 JDK 自带注解（如 @Deprecated）风格一致

别把它当成运行时控制开关

@Documented 是纯文档工具链的一环，和功能逻辑完全无关：

它不会触发任何反射调用，也不影响注解处理器（APT）行为
去掉它，代码照常编译、运行、被反射读取（只要 @Retention 允许）
它的价值在于协作——新成员看文档就能立刻知道这个接口受版本约束，那个字段必须校验，不用翻源码猜意图

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