@Documented 是让注解文档可见的桥梁而非运行开关，需配合完整 JavaDoc 注释、正确 Javadoc 构建配置（如包路径、UTF-8 编码、private 支持）及 CI 强制检查才能生效。
@Documented 不是让注解“生效”的开关，而是让注解的说明真正被开发者看见的桥梁。它本身不改变运行逻辑，但能让团队成员在查阅 JavaDoc 时，一眼看懂某个注解是干什么的、怎么用、有哪些限制——前提是注解本身写得清楚，且文档生成流程配得对。
注解必须自带完整 JavaDoc
只加 @Documented 却不写文档注释，等于贴了个空标签。生成的 JavaDoc 里只会显示注解名，没有解释、没有参数说明、没有使用场景，别人看了还是得翻源码。
- 用 /** */ 写正式文档注释，别用 // 或 /* ... */
- 每个 public 属性都要用 @param 明确说明用途、默认值和取值范围
- 正文开头用 @summary 一句话概括核心作用，比如“标记需进行权限校验的 REST 接口”
- 补充适用位置（如仅限 controller 方法）、典型误用示例、与其他注解的配合关系
构建过程要确保注解类被纳入文档
Javadoc 工具默认只扫描 public 类型，且不会自动包含所有包。如果注解定义在 internal 包或未显式指定路径，它就根本不会出现在最终文档里。
- 执行 javadoc 命令时，明确指定注解所在包，例如：javadoc -package com.example.annotation
- 中文注释务必加上编码参数：-encoding UTF-8 -docencoding UTF-8，否则乱码直接废掉可读性
- 若注解用于 private 方法或字段，需额外加 -private 参数，否则 Javadoc 默认忽略
- Maven 项目中，在 maven-javadoc-plugin 的配置里启用 <show>private</show> 和编码设置
把它放进协作规范和 CI 流程
靠人自觉写文档容易遗漏。把 @Documented 的使用变成硬性要求，才能稳定产出高质量 API 文档。
立即学习“Java免费学习笔记（深入）”；
- 所有对外暴露的自定义注解（尤其框架层、中间件层）必须标注 @Documented
- CI 构建阶段加入检查：扫描所有注解类，若缺少 JavaDoc 或未标注 @Documented，则构建失败
- 结合 IDE 提示，IntelliJ 在悬停时会展示带 @Documented 的注释内容，提升编码现场理解效率
- 将生成的 JavaDoc 部署为静态站点，与 Swagger、REST Docs 页面并列，形成统一开发者门户
它不复杂，但容易忽略细节。写好注释、配对构建、纳入流程，三者缺一不可。
