@Documented 的作用是使自定义注解被 Javadoc 工具收录，前提是注解类配有标准 Javadoc 注释且构建时包含源码；它不自动生成文档，但能提升协作效率——新成员可直接查阅 API 文档或 IDE 悬停提示理解注解用途、参数及使用场景。
@Documented 是 Java 中一个元注解，它的作用是让自定义注解在生成 Javadoc 时被包含进去。但要注意：它本身不会生成文档，只是“告诉 Javadoc 工具：这个注解值得被记录”。真正提升开发效率的关键，在于让团队成员一眼看懂注解的用途、参数和使用场景——而这需要配合规范的注释 + 正确的 Javadoc 配置。
为什么 @Documented 能提升协作效率
当一个注解被 @Documented 标记后，只要你在注解类上写了标准 Javadoc（如 /** 描述... */），执行 javadoc 命令生成 API 文档时，该注解就会出现在文档的“Annotation Types”章节中，并附带你写的说明、参数说明（@param）、返回说明（@return）等。
这对团队协作很实用：
- 新成员查阅接口或配置类时，鼠标悬停或点开 Javadoc 就能看到 @LogExecutionTime 的作用，而不用翻源码；
- IDE（如 IntelliJ）能自动解析并展示带格式的注释，提升编码时的上下文感知能力；
- 在 Spring Boot 等框架中，自定义条件注解（如 @ConditionalOnProperty）被广泛使用，清晰的文档能减少误用。
正确使用 @Documented 的三步操作
要让注解真正“可文档化”，光加 @Documented 不够，需同时满足：
- 在注解定义类上方添加标准 Javadoc 注释（以
/**开头，含功能描述、@param、@since 等） - 注解类本身必须用
@Documented标记（通常和其他元注解一起使用） - 构建 Javadoc 时确保未忽略注解源码（Maven 默认会包含，Gradle 需确认
javadoctask 包含src/main/java）
一个实际例子：可文档化的日志注解
比如定义一个记录方法执行时间的注解：
Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。
立即学习“Java免费学习笔记（深入）”；
/**
* 标记方法，自动记录其执行耗时（单位：毫秒）
* <p>
* 示例：
* {@code @LogExecutionTime(level = LogLevel.INFO)}
*
* @param level 日志级别，默认为 WARN
* @since 1.2
*/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented // ? 关键：声明此注解应出现在 Javadoc 中
public @interface LogExecutionTime {
LogLevel level() default LogLevel.WARN;
}生成 Javadoc 后，这个注解会单独成页，字段 level() 也会被解析为带说明的属性，IDE 悬停提示也更完整。
常见误区提醒
很多人以为加了 @Documented 就“自动出文档”，其实容易踩坑：
- 没写 Javadoc 注释 → 即使加了 @Documented，生成的文档也是空的或只有签名
-
注解用在 private 方法上 → 默认 Javadoc 不生成 private 成员文档，需加
-package或-private参数 - Maven 多模块项目中未聚合 Javadoc → 注解在 core 模块，但文档只生成了 api 模块，导致丢失
- 混淆了 @Documented 和 @Retention → @Documented 控制“是否进文档”，@Retention(RUNTIME) 才控制“运行时是否可用”，两者职责不同
