加@Documented只是让注解“能被看见”的第一步，真正起作用需配套JavaDoc注释、正确声明@Retention和@Target、规范文档生成流程，并在IDE悬停和OpenAPI文档中联动生效。
加 @Documented 只是让注解“能被看见”的第一步，真正起作用靠的是配套的 JavaDoc 注释、正确的元注解声明和规范的文档生成流程。
注解类本身必须写完整 JavaDoc
@Documented 不会自动生成说明文字，它只负责把已有的注释内容搬运进 HTML 文档。如果注解类没写 JavaDoc，生成的页面里只会显示 @MyLog 这样一行代码，没有任何解释。
- 必须用 /** */ 块注释，禁用
//或/* */行注释 - 类级注释要讲清用途、适用场景、典型用法（例如：“用于标记需审计的日志方法，仅支持 public 方法”）
- 每个 public 属性都要配 @param，说明用途、默认值、取值范围（如：
@param timeout 超时毫秒数，默认 3000，最小 100） - 建议补充 @since（首次引入版本）、@see（关联处理器或配置类）
声明时必须搭配 @Retention 和 @Target
@Documented 单独存在无效。Javadoc 工具需要从 class 文件中读取注解信息，这就要求它在编译后依然存在，并且编译器知道它能用在哪些位置。
- @Retention(RetentionPolicy.RUNTIME)：确保注解保留在 .class 中，javadoc 才能提取
- @Target({ElementType.METHOD, ElementType.TYPE})：明确可用位置，否则编译可能报错
- 缺一不可——哪怕写了完整注释，若 @Retention 是 SOURCE，javadoc 就看不到该注解
生成文档时要覆盖注解包并指定编码
即使注解写得再规范，生成命令漏掉包路径或忽略中文编码，文档照样不可读。
立即学习“Java免费学习笔记（深入）”；
- 命令行执行时必须包含注解所在 package，例如：
javadoc -d docs com.example.annotation - 含中文注释必须加：
-encoding UTF-8 -docencoding UTF-8 -charset UTF-8，否则出现乱码 - 若注解用于 private 方法或字段，需显式加 -private 参数，否则 javadoc 默认跳过
- Maven 构建中应配置
<includePackageNames>com.example.annotation.*</includePackageNames>
与开发环境和文档平台联动使用
@Documented 的价值不仅在静态 HTML 页面，更体现在日常开发流中实时生效。
- IntelliJ / VS Code 悬停提示会直接展示带 @Documented 的注解说明，无需切出代码
- 配合 Swagger 或 Spring REST Docs，能将注解语义（如
@ApiResponse(code = 401)）自动注入 OpenAPI 文档 - 把生成的 JavaDoc 部署为内部静态站点，和接口文档、部署手册并列，形成统一开发者门户
- CI 流程中可加入检查：扫描所有
@interface，若位于 public 包路径下却未标注 @Documented，则构建失败
