@Documented 使自定义注解在生成 Javadoc 时显示为标记，如 @ApiNote("此接口需登录后调用")，仅影响文档输出，不改变运行时行为，且必须标注在注解类型上而非使用处。
@Documented 是 Java 提供的一个元注解，它的作用是**让自定义注解在生成 Javadoc 时被包含进文档中**。默认情况下，Javadoc 工具不会把注解（尤其是自定义注解）显示在类、方法或字段的文档里；加上 @Documented 后，Javadoc 会自动将该注解的声明（如 @MyAnnotation）作为“标记”出现在生成的 HTML 文档对应位置。
如何让注解出现在 Javadoc 中
只需在定义注解时，用 @Documented 标记它即可：
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface ApiNote {
String value() default "";
}之后，在类或方法上使用它：
/**
* 用户服务入口
*/
@ApiNote("此接口需登录后调用")
public class UserService { ... }运行 javadoc 命令生成文档后，@ApiNote 就会显示在 UserService 的类文档顶部（通常在“类描述”下方、“作者”上方），格式类似：
注解：@ApiNote("此接口需登录后调用")
@Documented 不影响注解的运行时行为
它只影响 Javadoc 输出，和注解是否保留（@Retention）、能标注在哪（@Target）无关。即使你设为 RetentionPolicy.SOURCE，只要加了 @Documented，Javadoc 仍会显示它——因为文档生成阶段早于编译后期，只依赖源码中的注解语法。
- 不加
@Documented：Javadoc 完全忽略该注解，无论是否在源码中写了 - 加了但没写 Javadoc 注释：注解仍会显示，但不会带额外说明
- 配合
@see或{@link}可在注解值里做链接，增强可读性
常见误区提醒
-
@Documented是给「注解类型本身」加的，不是给使用注解的地方加的 - 它不会把注解的
value()内容自动渲染成段落文字，只展示注解调用语句（如@ApiNote("xxx")） - 如果想让说明文字更丰富，建议在类/方法的 Javadoc 注释中手动写
@see ApiNote或用{@link ApiNote}引导读者 - 标准注解如
@Override、@Deprecated本身就自带@Documented，所以你总能在 JDK 文档里看到它们
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
