@documented元注解使自定义注解自动出现在javadoc中，提升可维护性与协作效率；需配合@retention(runtime)和精准@target使用，避免用于内部或低信息量注解，并应集成ci/cd确保文档同步更新。
在Java工程化实践中，@Documented 是一个常被忽略却极具价值的元注解。它本身不改变注解的运行时行为，但能显著提升代码可维护性和团队协作效率——只要被标注的注解出现在类、方法或字段上，Javadoc 工具就会自动将其包含在生成的文档中。
让自定义注解“看得见”
很多团队会定义诸如 @ApiVersion、@DeprecatedSince 或 @TenantAware 这类业务语义注解，但默认情况下，它们不会出现在 Javadoc 输出里。用户查阅 API 文档时，根本看不到这些关键约束或约定。
只需在注解定义上添加 @Documented，就能让其“浮出水面”：
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface ApiVersion {
String value();
}
这样，当开发者为某个接口加上 @ApiVersion("v2")，生成的 Javadoc 页面中，该注解及其值就会清晰显示在方法签名下方。
与 @Retention 和 @Target 配合使用更规范
@Documented 通常不是单独使用的。它需要和 @Retention（决定注解保留策略）以及 @Target（限定使用位置）协同，构成完整注解契约：
-
@Retention(RetentionPolicy.SOURCE)的注解无法在运行时读取，也不建议加@Documented，因为仅用于编译期检查，文档意义有限； -
@Retention(RetentionPolicy.RUNTIME)的注解最常用，配合@Documented能兼顾运行时反射和文档可见性； -
@Target要准确限定作用范围，比如@ApiVersion不应允许加在局部变量上，否则文档会显得混乱且无意义。
避免文档“噪音”，合理控制粒度
不是所有注解都适合加 @Documented。以下情况建议谨慎或不加：
- 纯框架内部使用的注解（如 Spring 的
@Autowired），由框架自行处理，暴露给业务开发者反而造成干扰； - 大量重复、低信息量的标记型注解（如
@Loggable仅表示打日志，无参数且无业务含义），容易稀释文档重点； - 处于快速迭代中的实验性注解，尚未稳定，提前写入文档可能引发误解。
判断标准很简单：这个注解是否承载了需要被调用方明确知晓的契约、约束或语义？如果是，就值得被文档化。
集成到 CI/CD 中，确保文档同步更新
光加了 @Documented 不够，还要保证 Javadoc 构建真正执行并发布。可在 Maven 的 pom.xml 中配置：
<plugin><groupid>org.apache.maven.plugins</groupid><artifactid>maven-javadoc-plugin</artifactid><version>3.5.0</version><executions><execution><id>attach-javadocs</id><goals><goal>javadoc</goal></goals></execution></executions></plugin>
再结合 CI 流程（如 Jenkins 或 GitHub Actions），每次推送代码后自动生成并部署 Javadoc，才能让 @Documented 发挥实际价值。
不复杂但容易忽略——一行 @Documented，换来的是团队成员对业务规则的统一理解，是新人上手时少查源码、多看文档的体验提升。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
