Javadoc 的 {@value} 标签支持跨类引用 public static final 常量，只需提供带完整包路径的 package.Class#field 形式即可，无需复制常量定义，确保文档与源码值严格一致。

javadoc 的 {@value} 标签支持跨类引用 `public static final` 常量，只需提供带完整包路径的 `package.class#field` 形式即可，无需复制常量定义，确保文档与源码值严格一致。

在编写工具类的 Javadoc 时，若需展示来自其他类（如常量类）的字面值，应避免硬编码或重复声明——这既违背 DRY 原则，也易导致文档与实际值脱节。Javadoc 提供的 {@value} 内嵌标签正是为此设计：当用于 @return、@param 或普通描述文本中时，它会在生成的 HTML 文档中自动展开为该常量编译期确定的实际值（仅限 public static final 基本类型或 String）。

正确用法要求显式指定全限定名（fully qualified name），格式为：

{@value com.example.Constants#SOME_CONSTANT}

例如，假设有如下常量类（位于 com.example 包下）：

package com.example;

public class Constants {
    public static final String SOME_CONSTANT = "theVal";
}

则在 CoolUtil 类的 Javadoc 中应这样引用：

deep-java-review

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

下载

/**
 * Creates a MyObj instance initialized with the default value.
 *
 * @return a MyObj based on {@value com.example.Constants#SOME_CONSTANT}
 */
public static MyObj generateIt() {
    return new MyObj(Constants.SOME_CONSTANT);
}

✅ 编译后生成的 Javadoc 将显示：

Returns: a MyObj based on "theVal"

⚠️ 注意事项：

• 必须使用完整包路径（如 com.example.Constants），不能省略或使用相对名；
• 目标字段必须是 public static final，且类型为 boolean、byte、char、short、int、long、float、double 或 String；
• 若常量类未被 javadoc 工具扫描（如未包含在 -sourcepath 或模块路径中），将报错 warning: no @value reference found；
• 不支持引用枚举常量、非静态字段或运行时计算的值（如 new String("val")）；
• IDE（如 IntelliJ）可能不实时渲染 {@value}，需通过 javadoc 命令行或 Maven maven-javadoc-plugin 生成最终 HTML 验证效果。

通过这种方式，你既能保持代码的单一事实来源（Single Source of Truth），又能使 API 文档具备可读性与准确性——值随代码变更自动同步，彻底规避手动维护带来的风险。

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