@documented 是元注解，用于使自定义注解出现在 javadoc 文档中，需配合完整文档注释、@param 说明及正确 javadoc 扫描路径才能生效，与 @retention 职责不同。
@Documented 是让自定义注解真正“被看见”的关键一环——它不改变代码行为，但决定了你的注解会不会出现在生成的 Javadoc 文档里。
注解本身不会自动进文档
Java 中的普通注释（// 或 /* */）和文档注释（/** */）天然会被 javadoc 提取；但你写的自定义注解，比如 @ApiVersion 或 @Retryable，默认是隐身的。哪怕你在类上加了 @ApiVersion(2)，生成的 HTML 页面里也不会出现这行信息。
除非你在注解定义上明确加上 @Documented：
- 它是元注解，只能用在
@interface上，不能用在类、方法或字段上 - 没有属性，不带括号，直接写在注解声明上方即可
- 它只控制“注解是否被列出”，不管注解参数怎么用、也不解析文档注释内容
光加 @Documented 还不够
加上 @Documented 只是第一步。要让使用者真正看懂这个注解，还得配套做三件事：
- 注解类本身必须有完整的
/** */文档注释，说明用途、设计意图和典型场景 - 每个 public 属性都要用
@param明确解释：作用、默认值、合法取值范围 - 执行 javadoc 命令时，确保扫描到了该注解所在的包，例如：
javadoc -package com.example.annotation
否则，文档里只会显示一行干巴巴的 @ApiVersion(2)，没人知道它代表什么。
验证它有没有生效
最直接的办法就是对比生成结果：
- 先用
@Documented定义一个注解，再在某个类或方法上使用它 - 运行命令：
javadoc -encoding UTF-8 -docencoding UTF-8 -d docs YourClass.java - 打开生成的 HTML，在类/方法文档顶部查看是否有 “Annotations: @YourAnnotation(...)” 这一行
- 去掉
@Documented后重试，这一行就会消失
它和 @Retention 不是一回事
经常有人混淆这两个注解：
-
@Retention(RetentionPolicy.RUNTIME)决定注解能不能在运行时通过反射读取 -
@Documented只管它在 Javadoc 文档里显不显示 - 两者常一起用，但职责完全独立：一个面向程序执行，一个面向人看文档
比如 Spring 的 @Transactional 就同时标注了这两个元注解——既支持运行时代理增强，也方便开发者查阅文档理解语义。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
