@Documented 使自定义注解及其JavaDoc出现在生成的JavaDoc文档中，提升API可读性；需配合完整注释、正确构建配置及文档可见性设置才生效。

@Documented 是 Java 中一个关键的元注解，它的作用很直接：让自定义注解出现在生成的 JavaDoc 文档中。它本身不改变程序行为，但能显著增强公共 API 的可读性与协作效率——前提是配合规范的注释习惯和合理的文档生成流程。

为什么 @Documented 能提升 API 可读性

当一个注解被 @Documented 标记后，Javadoc 工具在生成 HTML 文档时，会把该注解及其属性说明一并纳入对应类、方法或字段的文档页。使用者无需翻源码，就能看到：

• 这个注解是干什么的（通过 @summary 或注释正文）
• 它支持哪些参数（@param 标签描述）
• 适用场景和约束（如“仅用于 controller 层方法”）
• 是否可重复使用、是否继承等行为特征（由其他元注解体现，@Documented 让这些信息可见）

正确使用 @Documented 的三个前提

它不是“开关式”功能，必须搭配以下实践才真正生效：

• 注解本身需带完整 JavaDoc 注释：用 /** ... */ 包裹，而非单行 // 或 /* ... */
• 注解属性要有明确说明：每个 public 属性都应在注释中用 @param name 解释用途、默认值、取值范围
• 构建时启用 JavaDoc 输出且包含该注解所在包：例如执行 javadoc -package com.example.annotation，确保注解类被扫描到

典型错误与改进建议

常见误区会削弱 @Documented 的价值：

• 只加 @Documented，但注解类没写任何 JavaDoc —— 文档里只显示注解名，无解释
• 注释写成中文但未配置编码（如未加 -encoding UTF-8 -docencoding UTF-8）—— 出现乱码，可读性归零
• 注解用于 private 方法，而 Javadoc 默认不生成 private 成员文档（需显式加 -private 参数）—— 用户根本看不到

建议统一要求所有对外暴露的自定义注解（尤其是框架层、中间件层）必须带 @Documented，并纳入 CI 流程检查：若注解类缺少 JavaDoc，构建失败。

与其他文档手段协同增效

@Documented 是 Java 原生文档链的一环，不是孤立方案：

• 搭配 Swagger/OpenAPI：注解（如 @ApiParam、@ApiResponse）被工具识别后，自动注入接口文档
• 结合 IDE：IntelliJ 或 VS Code 在悬停提示中展示带 @Documented 的注解说明，提升实时可读性
• 服务化文档：将生成的 JavaDoc 部署为静态站点，与 Spring REST Docs 或 NSwag 页面并列，形成统一开发者门户