@documented 是自定义注解被 javadoc 提取的前提，但真正生成清晰文档需三要素：注解类含完整 javadoc、正确配置 @retention(runtime) 和 @target、生成时设置 utf-8 编码及 -private 等参数，并通过 ci 强制规范。
@Documented 不是自动让文档变漂亮的开关，而是让自定义注解“能被看见”的前提。真正让 API 文档清晰有用，靠的是三件事：注解类写得清楚、生成过程配得准、团队用得规范。
注解类必须自带完整 JavaDoc
光加 @Documented 没用——它只负责把已有注释“搬进 HTML”，不提供一个字的说明。如果注解类没写 JavaDoc，生成的文档里就只剩一个干巴巴的 @MyLog。
- 必须用 /** */ 块注释，不能用 // 或 /* */
- 类级注释讲清用途、典型用法、约束条件，比如：“仅用于 service 层方法，不可用于 private 方法”
- 每个 public 属性都要有 @param 说明，例如：@param level 日志级别，默认 INFO
声明时必须搭配 @Retention 和 @Target
@Documented 单独存在无效。Javadoc 需从 .class 文件中读取注解信息，这就要求它在运行时仍存在，且编译器知道它能标在哪种元素上。
- @Retention(RetentionPolicy.RUNTIME)：确保注解保留在 .class 中
- @Target({ElementType.METHOD, ElementType.TYPE})：明确可用位置，否则编译失败
- 缺一不可——哪怕写了完整注释，若 @Retention 是 SOURCE 或 CLASS，javadoc 依然看不到
生成文档时注意编码与可见性设置
中文注释乱码、private 成员不显示，不是 @Documented 的问题，而是 javadoc 命令配置不到位。
- 命令行加参数：-encoding UTF-8 -docencoding UTF-8 -charset UTF-8，避免中文变问号
- 若注解用在 private 方法上，需显式加 -private 参数，否则默认跳过
- IDEA 中生成时，在 “Other command line arguments” 栏填入上述参数，Locale 设为 zh_CN 让界面语言也为中文
团队协作中建议强制规范
靠个人自觉容易遗漏。可将 @Documented + 完整 JavaDoc 设为硬性要求，并接入 CI 流程。
- 所有对外暴露的自定义注解（如框架层、中间件层）必须带 @Documented
- 用 checkstyle 或自定义脚本检查：注解类是否含 JavaDoc、是否含 @Retention(RUNTIME)、是否含 @Target
- CI 构建阶段执行验证能否成功生成，失败即阻断发布
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
