@documented 是 java 元注解，使被标记注解在生成 javadoc 时显示其声明（如 @apiversion("v2")），但不解析值或解释含义；需配合人工 javadoc 注释说明用途、属性等。
@Documented 是 Java 提供的一个元注解，作用是**让被它标记的注解在生成 Javadoc 时自动包含其声明信息**。但它本身不生成配置文档，也不解析注解值；它只影响 Javadoc 工具是否把该注解的使用“显示出来”。
注解本身要被 @Documented 标记
只有注解类上显式加了 @Documented，Javadoc 才会在类、方法、字段等使用该注解的地方，把注解名（如 @ApiVersion("v2")）作为文档的一部分渲染出来。
deep-java-review
下载
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
- 没加
@Documented：Javadoc 会忽略注解的存在，即使你写了@Deprecated或自定义注解，也不会出现在生成的 HTML 中 - 加了
@Documented：Javadoc 会保留注解的声明形式（比如@MyConfig(value = "test")），但不会展开解释它的含义或参数含义——这部分得靠你写 Javadoc 注释补充
Javadoc 要启用注解支持（默认已开启）
现代 JDK（8+）的 javadoc 工具默认识别并展示 @Documented 注解，无需额外开关。但需确保：
- 运行
javadoc时包含目标源码（含注解定义和使用处） - 注解类编译后在 classpath 中（否则 javadoc 可能无法解析注解类型，显示为
@UnknownAnnotation） - 如果用了模块系统（module-info.java），注意导出注解所在的包
真正让“配置”可读，还得靠人工写 doc 注释
@Documented 只负责“显示注解语法”，不负责“说明配置意义”。想让 Javadoc 对使用者真正有用，你需要：
- 在注解类上用
/** ... */写清楚用途、属性含义、默认值等 - 在使用该注解的类/方法上，也补充说明为什么用、怎么配、典型场景
- 例如：
/*** 标记接口的版本控制，用于网关路由匹配。* @see ApiVersion#value()*/@Documented@Retention(RetentionPolicy.RUNTIME)@Target(ElementType.TYPE)public @interface ApiVersion {String value() default "v1";}
常见误区提醒
-
@Documented不等于“自动生成配置文档”——它不提取value值，也不生成表格或配置项列表 - 不能替代 Spring Boot 的
@ConfigurationProperties+@Validated配置文档方案 - 如果希望导出结构化配置说明（如 YAML 示例、属性清单），需要配合其他工具（如 Spring Configuration Metadata、Dokka、或自定义 Doclet）
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
