@documented是启用注解文档可见性的标记型元注解，需配合完整javadoc注释和正确javadoc命令三步联动，才能使注解在javadoc及ide中可读可用。

@Documented本身不配置，它只是启用注解文档可见性的开关。真正让注解在JavaDoc里“可读、可用、可理解”，靠的是三步联动：注解定义加@Documented、注解类写完整JavaDoc、生成时正确执行javadoc命令。

注解定义必须带上@Documented

它是个标记型元注解，无参数，直接写在自定义注解声明上方即可：

• 只作用于@interface类型，不能用于类、方法或字段
• 和@Retention(RetentionPolicy.RUNTIME)常搭配，但两者职责分离：一个管运行时反射，一个管文档显示
• 对外暴露的注解（如@ApiVersion、@Retryable、@NotBlank）必须加，CI流程中建议扫描public包路径下未加@Documented的@interface并阻断构建
• 内部工具类或测试专用注解（如@MockBean简化版）可不加，但需明确归入internal.*包或标注@Internal

注解类要配完整的JavaDoc块注释

@Documented只负责“搬运”，不负责“写内容”。没写JavaDoc，生成的文档就只剩一行@MyLog(level = "INFO")，毫无说明力：

deep-java-review

Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...

下载

• 必须用/** */包裹，禁用//或/* */注释
• 每个public属性都要有@param说明，包括用途、默认值、取值范围（例如：@param timeout 超时毫秒数，默认5000，最小100）
• 建议补充@since（首次引入版本）、@see（关联配置类或处理逻辑）
• 首行简明概括语义，例如：/** 标记该接口支持的最低API版本 */

生成JavaDoc时覆盖包路径并指定UTF-8编码

即使注解写得再规范，生成命令漏掉包或忽略中文编码，文档照样不可读：

• 命令行必须包含注解所在package，例如：javadoc -d docs com.example.annotation
• 含中文注释必须加：-encoding UTF-8 -docencoding UTF-8，否则出现乱码
• 若注解用于private方法或字段，需显式加-private参数，否则javadoc默认跳过
• IDE中生成时，“Visibility”设置需匹配实际暴露范围（Package或Private）

与开发环境联动提升实效性

@Documented的价值不止于HTML文档，更体现在日常编码中：

• IntelliJ / VS Code悬停提示会直接展示带@Documented的注解说明，无需切出代码
• 配合Swagger或Spring REST Docs，能将注解语义（如@ApiResponse(code = 401)）自动注入OpenAPI文档
• 把生成的JavaDoc部署为静态站点，与接口文档、部署手册并列，形成统一开发者门户

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南