@documented 的核心作用是使自定义注解显式展示在 javadoc html 文档中，如 @apiversion(2) 会显示在类或方法文档顶部；需配合完整 javadoc 注释、正确生成命令（含包路径、编码、-private 参数）及工具链集成，才能实现注解“被看见”。
因为注解是公共API的一部分，不加@Documented，使用者就看不到它在文档里的存在——哪怕代码里用得再规范，文档里也是一片空白。
让注解真正“被看见”
@Documented 的核心作用，是把自定义注解本身作为元数据，显式展示在 Javadoc 生成的 HTML 页面中。比如一个 @ApiVersion(2) 注解，加了 @Documented 后，会在类或方法的文档页顶部直接显示：
- Annotations: @ApiVersion(2)
- 点击进去还能看到注解类的完整说明、每个属性的含义和默认值
- 没加 @Documented，这行信息完全不会出现，使用者只能翻源码猜用途
避免“有注解，无解释”的陷阱
只加 @Documented 不够，必须配合完整的 JavaDoc 注释，否则文档里只剩干巴巴的注解名：
- 注解类必须用 /** */ 写块注释，不能用 // 或 /* */
- 每个 public 属性都要配 @param，说明用途、默认值、取值范围（如 @param level 日志级别，默认 INFO）
- 建议补充 @since 和 @see，方便追溯版本和关联逻辑
确保文档生成环节不掉链子
即使注解写得再好，生成命令漏关键参数，文档照样不可用：
- 命令中必须包含注解所在包路径，例如 javadoc -d docs com.example.annotation
- 含中文注释必须指定编码：-encoding UTF-8 -docencoding UTF-8
- 若注解用于 private 方法或字段，需显式加 -private 参数，否则 javadoc 默认跳过
融入日常开发流程才真正生效
@Documented 的价值不止于静态 HTML，更在开发者每天接触的工具链里：
- IntelliJ / VS Code 悬停提示会直接显示带 @Documented 的注解说明，不用切出代码
- 配合 Swagger 或 Spring REST Docs，能将 @ApiResponse、@ApiParam 等语义自动注入 OpenAPI 文档
- 把生成的 JavaDoc 部署为静态站点，和接口文档、部署手册并列，形成统一开发者门户
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
