@documented 的作用是让自定义注解出现在 javadoc 生成的 html 文档中，提升 api 可读性；它需与 @retention(retentionpolicy.runtime) 和 @target 协同生效，并依赖完整 javadoc 注释和正确构建配置。
@Documented 的作用很明确：让自定义注解出现在 Javadoc 生成的 HTML 文档中。它不改变代码行为，也不参与编译或运行时逻辑，只影响文档输出——但这个“只影响文档”的动作，恰恰是提升 API 可读性的关键一环。
注解出现在文档里，开发者才真正“看见”它
默认情况下，Javadoc 只显示 JDK 自带的少数几个注解（如 @Deprecated、@Override）。自定义注解哪怕用得再规范，只要没加 @Documented，生成的文档里就完全不可见。用户翻到某个接口方法页面，可能只看到签名和描述，却看不到上面标注的 @ApiVersion("2.1") 或 @Validated —— 这些关键契约信息被隐藏了。
- 加了 @Documented，注解会紧挨着方法签名显示，格式清晰（如：
@ApiVersion("2.1")） - 配合完整的 JavaDoc 注释，还能一并展示该注解的用途、参数含义、适用限制等
- IDE 悬停提示也会读取这些内容，实现“所见即所得”的实时理解
必须搭配的三个元注解才能生效
@Documented 不是独立起效的开关，它需要和另外两个元注解协同工作：
- @Retention(RetentionPolicy.RUNTIME)：确保注解保留在 class 文件中，javadoc 工具才能从字节码里读取到它
- @Target：声明注解可用的位置（比如 ElementType.METHOD），否则编译直接失败
- @Documented：告诉 javadoc：“这个注解的信息，请写进 HTML 文档”
三者缺一不可。如果用了 @Retention(RetentionPolicy.CLASS)，即使加了 @Documented，javadoc 也找不到注解数据。
文档能被看见，还得靠生成配置和注释质量
光在注解定义上加 @Documented 还不够。要让最终文档真正有用，还需注意：
- 注解类本身必须用
/** */写完整 JavaDoc，不能只写单行注释 - 每个 public 属性都要用
@param明确说明用途、默认值、是否必填 - 执行 javadoc 命令时，需确保目标包路径被包含（例如
javadoc -package com.example.annotation） - 若注解用于 private 成员，需显式加
-private参数，否则 javadoc 默认跳过
和其它文档工具形成合力
@Documented 是 Java 原生文档链的基础环节，不是孤立方案：
- Swagger/OpenAPI 工具可识别带 @Documented 的注解（如 @ApiResponse），自动注入 REST 接口文档
- Spring REST Docs 或 NSwag 生成的页面，可以和 javadoc 静态站点并列部署，统一开发者门户
- CI 流程中可加入检查：若对外暴露的注解类缺失 JavaDoc，构建失败，强制保障文档质量
