@documented的作用是让自定义注解出现在javadoc生成的html文档中，需配合@retention(runtime)和@target使用，且注解类须有完整javadoc，生成时注意可见范围与编码。
@Documented 的作用就是让自定义注解出现在 Javadoc 生成的 HTML 文档里。它不改变代码运行逻辑，只影响文档输出——加了它，你在类、方法或字段上写的 @ApiVersion("3.0") 或 @Book(name = "Effective Java") 就会清清楚楚显示在对应文档页面中；不加，Javadoc 就当它不存在。
注解要被看见，得满足三个条件
单独加上 @Documented 不够，必须和另外两个元注解配合使用：
- @Retention(RetentionPolicy.RUNTIME)：确保注解信息保留在编译后的 class 文件中，Javadoc 工具才能读到
- @Target：明确声明这个注解能用在哪些位置（比如 METHOD、TYPE），否则编译直接报错
- @Documented：告诉 Javadoc：“请把这个注解连同它的值一起写进 HTML 文档”
注解类本身要有完整 JavaDoc
光有 @Documented，但注解类没写说明，文档里只会显示 @MyAnnotation 这几个字，用户根本不知道它是干啥的。正确做法是：
- 用 /** */ 写多行 JavaDoc，而不是 // 或 /* */
- 每个 public 属性都用 @param 描述用途、默认值、取值范围
- 用 @since、@see 等补充上下文，比如“仅用于 REST 接口版本控制”
生成文档时要注意编码和可见范围
Javadoc 默认只生成 public 和 protected 成员的文档。如果你把注解用在 private 方法上，又没加 -private 参数，那它压根不会出现在文档里。另外：
- 命令行生成时建议加上 -encoding UTF-8 -docencoding UTF-8，避免中文注释变乱码
- IDEA 中右键 → Generate JavaDoc → 勾选对应模块即可，无需额外开关
- 确保 javadoc 命令扫描到了注解所在的包，例如：javadoc -package com.example.annotation
它不是万能的，但很关键
@Documented 只管文档展示，不影响运行时行为，也不参与编译检查。如果注解用了 @Retention(RetentionPolicy.SOURCE)，哪怕加了 @Documented，class 文件里没有它，Javadoc 也抓不到。它不复杂但容易忽略。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
