Java开发文档集成：如何编写带有@Documented的注解-java教程-PHP中文网

要让自定义注解出现在 javadoc 中，需同时满足：①用 @documented 修饰注解；②指定 @retention(retentionpolicy.runtime 或 class)；③正确声明 @target；④在注解及使用处添加 javadoc 注释。

java开发文档集成：如何编写带有@documented的注解

要让自定义注解出现在生成的 JavaDoc 中，关键不是简单加上 @Documented，而是它必须配合正确的注解声明方式和 Javadoc 工具链使用。

什么是 @Documented？

@Documented 是一个元注解，作用是告诉 Javadoc 工具：把这个注解本身（而不是仅其作用）也纳入生成的文档。它不会自动让注解的参数或用法说明出现，只决定“该注解是否应被记录在类/方法的文档里”。比如你给某个方法加了 @ApiStatus.Stable，加上 @Documented 后，Javadoc 页面中这个方法的描述下方才会显示 “@ApiStatus.Stable” 这行字。

正确声明一个可文档化的注解

声明时需满足三点：

用 @Documented 修饰你的自定义注解类型
指定合适的 @Retention(RetentionPolicy.RUNTIME) 或 CLASS（Javadoc 需要能在编译后读取到该注解）
明确 @Target，比如 ElementType.METHOD、ElementType.TYPE 等，否则编译器可能拒绝使用

示例：

OpenJDK 24

下载

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface ApiVersion {
    String value() default "1.0";
}

让注解用途真正体现在 Javadoc 中

@Documented 只控制“是否显示注解标记”，不控制“怎么写说明”。要让使用者清楚怎么用，还得靠 Javadoc 注释本身：

在注解定义上方写标准 Javadoc，说明用途、参数含义、典型场景
在被标注的类、方法等元素上，同样写 Javadoc，必要时解释为何此处用了该注解
运行 javadoc 命令时确保没加 -noqualifier 或过滤掉注解的选项

例如，在 @ApiVersion 上写：

/**
 * 标记 API 的版本号，用于兼容性管理。
 * 
 * @see ApiStatus
 * @since 2.1
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface ApiVersion {
    /**
     * 主版本号，格式如 "1.0"、"2.1-beta"。
     */
    String value() default "1.0";
}