@documented 用于让自定义注解出现在 javadoc 生成的 api 文档中，不影响 ide 显示；ide 显示注解依赖语法高亮与悬停提示，而快速文档（ctrl+q）能否展示其说明则取决于是否添加 @documented 及其源码 javadoc。
@Documented 是一个元注解，作用很明确：它告诉 JavaDoc 工具——“把这个注解本身也一并写进生成的 API 文档里”。也就是说，如果某个自定义注解（比如 @ApiPermission）加上了 @Documented，那么当用 javadoc 命令生成 HTML 文档时，这个注解的声明、参数、用途等信息就会出现在对应类或方法的文档页面中；否则，默认不出现。
为什么 IDE 里看不到 @Documented 的直接效果？
IDE（如 IntelliJ IDEA）本身不依赖 @Documented 来决定是否显示注解。它显示注解，靠的是语法高亮、代码补全、悬停提示这些基础能力，和注解有没有加 @Documented 没关系。哪怕没加，只要注解存在，IDE 就能识别并展示出来。
- 你在方法上写了
@ApiPermission，IDE 会标出它，鼠标悬停能看到注解定义 —— 这跟@Documented无关。 - 但如果你用
javadoc生成网页版 API 手册，且@ApiPermission没加@Documented，那手册里就查不到这个注解的说明，使用者无法知道它代表什么权限含义。
IntelliJ 中真正影响注解“可读性”的设置
IDE 对注解的呈现，更关键的是编辑器配置和文档渲染机制：
- 开启“渲染文档注释”后，
/** ... */注释（包括其中的@see、@link等标签）会以富文本形式显示，点击链接可跳转，字体可调大小 —— 这让 Javadoc 更易读，但不影响注解本身的显示逻辑。 - 按
Ctrl + Q（Windows/Linux）或Ctrl + J（macOS）调出“快速文档”，IDE 会自动提取当前元素的 Javadoc 内容，包括被@Documented标记的注解说明 —— 这是两者间接协同的地方：只有加了@Documented，快速文档里才可能包含该注解的完整描述。 - 在项目设置中启用“全部渲染 Javadoc”，能让所有文档注释默认展开，避免手动点装订区切换，提升浏览效率。
@Documented 不等于“在代码里高亮显示”
容易混淆的一点是：有人以为加了 @Documented，IDE 就会把使用该注解的地方加粗或变色。其实不会。注解的视觉样式由 IDE 主题和语言注入规则控制，不是由 @Documented 决定的。
- 想让某个注解更醒目？可以自定义颜色方案：进入 Settings → Editor → Color Scheme → Language Defaults → Annotations，调整注解文字颜色或背景。
- 想让注解带说明？得在它的源码里写好 Javadoc，例如：
/** 允许访问指定资源，需配合权限中心校验 */<br> @Documented<br> public @interface ApiPermission { ... }
什么时候必须加 @Documented？
当你设计的注解是给别人用的，尤其是要纳入公共 SDK 或对外发布的 API 文档时，加 @Documented 就很有必要：
- Spring 的
@Controller、@Service都加了@Documented，所以 Spring 官方文档里能查到它们的语义和用法。 - 如果你的团队内部框架定义了
@Retryable注解，又希望新成员看 Javadoc 就明白重试策略怎么配，那就该加。 - 不加也没错，只是文档里“少了一层说明”，使用者得翻源码才能理解注解意图。
