@Documented仅用于Javadoc文档生成，不参与代码生成；它作为元注解不影响编译、运行、APT或Lombok等工具，真正驱动代码生成的是注解处理器、Lombok插件、模板引擎或IDE脚本。
Java中@Documented本身不参与代码生成，它只是告诉Javadoc工具将该注解保留在生成的文档中。想靠它“自动生成代码”属于常见误解——它不触发编译期处理、不修改字节码、也不被IDE或构建工具直接用于生成源码。
为什么@Documented不能生成代码
@Documented是元注解（meta-annotation），作用域仅限于Javadoc。它的存在与否，对编译、运行、注解处理器（APT）或Lombok等代码生成工具完全无影响。比如：
- 哪怕你给自定义注解加上
@Documented，javac也不会因此多生成一行getter方法； - Spring Boot的
@ConfigurationProperties能生成元数据文件，靠的是专门的@ConstructorBinding和APT，不是@Documented； - Lombok的
@Data背后是JSR 269注解处理器，@Documented在其中只是让Lombok自己的注解出现在API文档里。
真正能驱动代码生成的机制
如果目标是“自动生成Java代码”，应聚焦以下实际可用的技术路径：
-
注解处理器（Annotation Processing Tool, APT）：在编译期扫描特定注解，生成
.java文件（如Room、MapStruct、AutoValue）； - Lombok：通过JVM Agent或编译器插件，在编译阶段重写AST，生成构造器、getter/setter等；
- 模板引擎+配置文件：用FreeMarker/Velocity读取JSON/YAML模型，生成DAO、DTO等批量代码；
- IDE插件或脚本：IntelliJ Live Templates、VS Code Snippets，或用Python脚本解析类结构后生成配套代码。
@Documented的合理使用场景
它唯一价值是提升文档可读性。当你开发公共SDK或框架时，建议为自定义注解添加@Documented：
立即学习“Java免费学习笔记（深入）”；
- 用户在IDE里按Ctrl+J（或Cmd+J）查看注解说明时，能看到你写的JavaDoc；
- Javadoc站点中，该注解会连同其说明一起出现在“Annotations”章节；
- 配合
@Retention(RetentionPolicy.RUNTIME)和@Target，构成完整、易用的注解设计。
一个典型示例
假设你写了一个校验注解@NonEmpty：
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented // ← 这行让Javadoc包含它
public @interface NonEmpty {
String message() default "must not be empty";
}
加上@Documented后，团队成员执行mvn javadoc:javadoc，就能在生成的HTML文档里直接看到@NonEmpty的用途和参数说明——这提升了协作效率，但没生成任何新Java类。
