@documented 是注解信息可见的必要条件，但需配合规范 javadoc、正确构建配置和合理使用范围才能使 api 文档真正有效。
@Documented 不是文档生成的“开关”，而是让注解信息真正可见的必要条件——但只加它远远不够，必须配合规范注释、正确构建和合理使用范围，才能让 API 文档真正帮上忙。
关键注解必须带 @Documented
对外暴露的自定义注解（比如权限校验 @RequiresRole、接口版本控制 @ApiVersion、参数校验 @Validated）都应明确加上 @Documented。这不是可选项，而是公共 API 的基本契约。
- 不加 @Documented，Javadoc 就不会显示该注解，使用者看到的只是“空方法”，不知道背后有哪层语义约束
- 框架层、中间件层、SDK 层的注解尤其要强制要求，CI 流程中可加入检查：扫描所有
@interface，若含 public API 但无 @Documented，构建失败 - @Documented 只能用在注解类型上，不能用于类或方法，否则编译报错
注解类本身要有完整 JavaDoc
@Documented 只负责“展示”，内容得靠注释来提供。一个没写 JavaDoc 的 @Documented 注解，文档里只会显示个名字，毫无意义。
- 注解类必须用
/** */块注释，不能用//或/* */行注释 - 每个 public 属性都要用
@param明确说明用途、默认值、是否必填、取值范围（例如：@param version 接口版本号，如 "v1" 或 "v2"，不可为空） - 正文需说明适用场景、典型用法、注意事项（例如：“仅用于 REST Controller 方法，不支持异步调用上下文”）
生成文档时要确保注解被扫描到
即使注解写了完整 JavaDoc 并加了 @Documented，如果构建流程没覆盖它，最终文档依然看不到。
- 执行 javadoc 命令时，必须显式包含注解所在包，例如：
javadoc -encoding UTF-8 -docencoding UTF-8 -d docs com.example.annotation - IDE 中生成 JavaDoc 时，检查“生成私有成员”选项是否勾选——如果注解用在 private 方法上，不勾选就看不到
- Maven 项目需配置 maven-javadoc-plugin，确保
<includepackagenames>com.example.annotation</includepackagenames>被纳入
与开发体验联动才真正生效
@Documented 的价值不仅体现在静态 HTML 文档里，更在日常编码中实时体现。
- IntelliJ 或 VS Code 悬停提示会直接显示带 @Documented 的注解说明，开发者写代码时就能理解意图，无需切出查源码
- 配合 Swagger 或 Springdoc，标注了 @Documented 的注解（如 @ApiResponse、@Parameter）会被自动提取进 OpenAPI 文档
- 把生成的 JavaDoc 部署为内部站点，和接口文档、部署手册并列，形成统一开发者门户，降低新成员上手成本
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
