@documented使自定义注解的javadoc说明可见于api文档和ide提示，强制规范注释习惯，并通过ci检查保障对外注解的文档完整性。
@Documented 本身不生成文档，但它让自定义注解“可被看见”——这是开源框架文档质量提升的关键一环。真正起作用的，是它把注解语义从代码里“搬进”JavaDoc，让使用者在查阅API时，一眼就明白这个注解干了什么、怎么用、有什么限制。
让注解说明直接出现在JavaDoc页面上
开源用户通常不会翻源码，而是依赖生成的JavaDoc站点快速理解API。加了 @Documented 的注解，只要配套完整注释，就会在类、方法或字段的文档页中显示出来，包括：
- 注解用途（通过 JavaDoc 的正文说明）
- 每个属性的作用、默认值、取值范围（用 @param 明确标注）
- 适用位置（如仅限 public 方法）、是否可重复、是否继承等行为特征（由其他元注解定义，@Documented 让这些信息可见）
强制规范注释习惯，倒逼文档完整性
@Documented 不是装饰，它是文档契约的触发器。它迫使团队必须为每个对外暴露的注解写完整 JavaDoc：
- 必须用 /** */ 块注释，禁用 // 或 /* */
- 每个 public 属性都要有 @param，比如 @param retryTimes 最大重试次数，默认3次，取值1–10
- 建议补充 @since（首次引入版本）、@see（关联配置类或处理逻辑），方便用户溯源
与构建流程和IDE联动，形成实时文档体验
文档价值不仅在静态HTML，更在日常开发中：
- IntelliJ 或 VS Code 悬停提示会直接展示带 @Documented 的注解说明，无需离开编辑器
- 配合 Swagger / Spring REST Docs，注解语义（如 @ApiResponse、@ApiParam）能自动注入 OpenAPI 文档
- 将生成的 JavaDoc 部署为静态站点，与接口文档、QuickStart 指南并列，构成统一开发者门户
纳入CI检查，守住文档底线
光靠自觉不够，需要机制保障：
- 所有位于 public 包路径下的自定义注解，必须标注 @Documented
- CI 流程中扫描 @interface，若未标注 @Documented 且属对外API，则构建失败
- 内部工具类或测试专用注解可豁免，但需明确归入 internal.* 包或标记 @Internal
