@documented仅声明注解可见性，真正生效需三要素协同：注解类配完整javadoc（含@param等标签）、搭配@retention(runtime)和@target、生成时覆盖注解包并指定utf-8编码。
@Documented 不是“加了就自动好使”的开关，它只负责把注解内容写进 Javadoc 页面，但能否真正帮到使用者，取决于你怎么声明、怎么写注释、怎么生成文档。
注解本身必须带完整 JavaDoc
只写 @Documented @interface ApiVersion { String value(); } 是不够的。Javadoc 页面上只会显示 @ApiVersion("2.0") 这一行，没有解释，没人知道它干啥用。
- 注解类要用
/** */块注释，开头写清楚用途，比如“标识接口兼容的 API 版本” - 每个 public 属性都得有
@param说明：取值范围、默认值、是否必填 - 建议加上
@since和@see，方便使用者关联上下文
三要素缺一不可
@Documented 单独存在没意义，必须和另外两个元注解配合使用，否则编译或运行时会出问题。
-
@Retention(RetentionPolicy.RUNTIME)：javadoc 工具读的是 class 文件，只有 RUNTIME 策略才能让注解信息保留在 class 中 -
@Target({ElementType.METHOD, ElementType.TYPE})：明确能用在哪儿，否则编译直接报错 -
@Documented：告诉 javadoc，“这个注解值得被用户看见”
生成文档时要覆盖到注解类本身
如果只对业务包执行 javadoc -d docs com.example.service，而注解定义在 com.example.annotation 包里，那文档里照样看不到注解说明。
- 确保 javadoc 命令包含注解所在的 package，例如
javadoc -d docs com.example.annotation com.example.service - IDE 中生成时，检查“Scope”是否设为 “All classes”，别漏掉 annotation 模块
- 中文注释要加参数：
-encoding UTF-8 -docencoding UTF-8 -charset UTF-8，不然全是乱码
结合开发流程形成规范
靠人自觉容易遗漏，最好把它变成可检查的硬性要求。
- 所有对外暴露的自定义注解（尤其是框架层、中间件层）必须加 @Documented
- CI 流程中加入检查：扫描注解类，若无 JavaDoc 或缺失 @Documented，构建失败
- IDE 模板预置标准注解结构，减少手动遗漏
- 搭配 Swagger 或 Spring REST Docs，让 @Documented 注解自动同步到接口文档里
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
