@documented是元注解，用于使自定义注解出现在javadoc生成的api文档中；它不影响普通注释，仅控制注解本身是否被javadoc工具识别并展示，需配合文档注释和标准标签共同完善文档。
Java源码注释和Javadoc文档不是一回事，@Documented的作用，就是让自定义注解“出现在生成的Javadoc里”——它不处理普通注释（如//或/* */），只影响你写的注解类是否被javadoc工具识别并展示。
@Documented是给注解加的“文档通行证”
普通注释（单行、多行、文档注释）天然会被javadoc提取；但自定义注解默认不会出现在API文档中。除非你在注解定义上明确标注@Documented，否则即使代码里用了这个注解，生成的HTML文档里也看不到它。
- 它是元注解，作用对象是“其他注解”，不是类或方法本身
- 没有属性，不带括号，直接写在
@interface声明上方即可 - 和
@Retention(RetentionPolicy.RUNTIME)常搭配使用，但两者职责不同：一个管“运行时能否反射读取”，一个管“文档里是否显示”
怎么验证@Documented生效了？
最直接的方式是用javadoc命令生成文档后对比查看：
- 先写一个带
@Documented的注解，比如：
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiVersion { int value() default 1; } - 再在某个类或方法上使用它：
@ApiVersion(2)
public class UserService { ... } - 执行命令：
javadoc -d docs UserService.java - 打开
docs/下的HTML页面，在类摘要或详情页顶部，你会看到类似“Annotations: @ApiVersion(2)”的说明行 - 如果去掉
@Documented再重试，这行就消失了
常见误区：它不管普通注释，也不自动补文档
@Documented不参与解析/** */里的内容，也不会把你的字段说明、参数描述自动塞进注解文档里。它只做一件事：把注解本身作为“已应用的元数据”显式列出来。
- 想让方法参数、返回值、异常等信息出现在Javadoc中，仍需手写
@param、@return、@throws等标准标签 - 想让自定义注解的含义更清晰，建议在它的
@interface定义上方加文档注释，比如：
/** 标记该接口支持的最低API版本 */
@Documented
public @interface ApiVersion { ... } - IDE（如IntelliJ）的提示框里能否显示注解，取决于IDE是否支持元注解解析，与@Documented无直接关系
实际项目中推荐这样用
当你设计的注解具有明确语义且需要被使用者理解时，加上@Documented是专业做法。典型场景包括：
- 框架级注解：如
@RestController、@Transactional，用户必须知道它在文档里代表什么行为 - 领域业务注解：如
@SensitiveData、@AuditLog，便于团队统一认知和审查 - 配置类上的组合注解：比如
@EnableMyFeature内部包含多个基础注解，加@Documented能让文档体现“这是一个启用开关”
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
