所有对外暴露的自定义注解必须加@documented并配完整javadoc，生成时需覆盖对应包、指定utf-8编码，且与ide及文档平台联动以实现开发全流程可见。
加了 @Documented 不等于注解就自动出现在 JavaDoc 里——它只是“声明可见”，真正要让使用者在文档中一眼看懂注解用途，得靠一整套规范动作。
所有对外暴露的自定义注解必须带 @Documented
只要这个注解会被其他模块、下游服务或外部开发者使用，就必须加上 @Documented。这不是可选项，而是 API 契约的一部分。比如框架层的 @ApiVersion、中间件层的 @Retryable、校验层的 @NotBlank，都应默认启用该元注解。
- CI 流程中可加入检查：扫描项目中所有
@interface，若未标注 @Documented 且位于public包路径下，则构建失败 - 内部工具类或测试专用注解（如
@MockBean的简化版）可不加，但需明确标记为@Internal或归入internal.*包
注解类本身必须写完整 JavaDoc 块注释
@Documented 只负责“搬运”，不负责“写内容”。如果注解类没写 JavaDoc，生成的文档里只会显示 @MyLog(level = "INFO") 这样一行代码，毫无解释力。
- 用
/** */包裹，禁用//或/* */ - 每个
public属性都要配@param，说明用途、默认值、取值范围（例如：@param timeout 超时毫秒数，默认 5000，最小 100） - 建议补充
@since（首次引入版本）、@see（关联配置类或处理逻辑）
生成 JavaDoc 时必须覆盖注解所在包并指定编码
即使注解写得再规范，生成命令漏掉包、忽略中文编码，文档照样不可读。
- 命令行执行时确保包含注解所在的 package，例如：
javadoc -d docs com.example.annotation - 含中文注释必须加：
-encoding UTF-8 -docencoding UTF-8，否则出现乱码 - 若注解用于
private方法或字段，需显式加-private参数，否则 javadoc 默认跳过 - IDE 中生成时注意 “Visibility” 设置为
Private或Package（视实际暴露范围而定）
与 IDE 和文档平台联动使用效果更佳
@Documented 的价值不仅在静态 HTML 页面，更在日常开发流中实时生效。
- IntelliJ / VS Code 悬停提示会直接展示带 @Documented 的注解说明，无需切出代码
- 配合 Swagger 或 Spring REST Docs，能将注解语义（如
@ApiResponse(code = 401)）自动注入 OpenAPI 文档 - 把生成的 JavaDoc 部署为静态站点，和接口文档、部署手册并列，形成统一开发者门户
