@documented 是让注解“被看见”的桥梁，确保自定义注解及其完整说明出现在 javadoc 中，需搭配 /* / 块注释、@param 说明及 ci 中显式启用 javadoc 并覆盖注解包，方可支撑 api 可读性与文档可信度。
@Documented 不是让注解“生效”的开关，而是让注解“被看见”的桥梁——它确保自定义注解及其说明完整出现在 JavaDoc 文档中，从而支撑企业级 API 的可读性、协作效率和文档可信度。
必须搭配完整 JavaDoc 注释才真正起作用
只加 @Documented 而不写 JavaDoc，生成的文档里只会显示一个空荡荡的注解名，毫无解释力。企业规范要求：
- 所有对外暴露的自定义注解（如
@ValidRole、@Idempotent、@AuditLog）必须用/** */块注释包裹 - 每个 public 属性必须用
@param明确说明用途、默认值、取值范围（例如：@param level 日志级别，支持 INFO/WARN/ERROR，默认 INFO） - 正文需包含一句话摘要（
@summary或首句）、适用场景、典型误用示例（如“不可用于异步方法”）
构建流程中要显式启用并覆盖注解包
JavaDoc 默认不扫描注解类，也不处理 private 成员。企业 CI 流程中应固化以下实践：
- Maven 构建时启用
javadoc:javadoc目标，并指定<includepackagenames>com.example.annotation.*</includepackagenames> - 命令行生成需带参数：
javadoc -encoding UTF-8 -docencoding UTF-8 -charset UTF-8 -package -private - 若注解用于 private 方法或字段，必须加
-private；否则调用方在文档中根本看不到该注解的使用痕迹
与 IDE 和文档平台联动才能发挥最大价值
@Documented 的价值不止于静态 HTML。企业级落地需打通三环：
- IDE 悬停提示：IntelliJ / VS Code 自动解析带 @Documented 的注解 JavaDoc，开发者写代码时即见说明
- Swagger/OpenAPI 集成：框架层注解（如
@ApiResponse）被工具识别后，自动注入 REST 接口文档 - 统一开发者门户：将生成的 JavaDoc 部署为内部静态站点，与 Spring REST Docs、NSwag 页面并列，形成一致入口
建议纳入代码门禁（CI Gate）强制检查
避免“写了 @Documented 却没写注释”的形式主义。可在 CI 中加入校验规则：
- 扫描所有
@interface文件，若含 @Documented 但无/**开头的块注释，则构建失败 - 检查注解类中每个 public 方法是否都有对应
@param，缺失则告警 - 结合 SonarQube 自定义规则，对注解文档覆盖率打分，纳入质量门禁阈值
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
