如何在javadoc中使用@value标签？

Question

我正在使用一个私有构造函数而不是枚举的类(这是一个要求).现在我正在尝试添加javadoc标记来记录每个public static final实体.

1)放置javadoc标签的首选位置:喜欢ob1还是ob2？

2)两个选项都会在IDEA中产生错误 @value tag must reference field with a constant intializer.

/**
 * {@value #ob1} object1 description
 */

public class MyClass {
    public static final Object ob1 = new Object();

    /**
     * {@value #ob2} object2 description
     */ 
    public static final Object ob2 = new Object();

    private MyClass() {}   
}

Answer 1

我不认为Kayaman的答案是足够的,因为问题是如何在javadocs中使用@value标签.

我认为问题在于被引用字段的值不是字面值.

在日食中,当你有

/**
 * {@value #ob2} object2 description
 */ 
public static final Object ob2 = new Object();

生成的Javadocs是{@value#ob2} object2 description.但是,当你有

/**
 * {@value #ob2} object2 description
 */ 
public static final String ob2 = "hello";

生成的Javadocs是"hello"object2 description(预期输出).

因此,总而言之,您在javadocs中正确使用@value标记,但只有在使用文字值初始化字段时才会正确呈现该值.

Answer 2

2) 这两个选项都会在 IDEA 中产生错误 @value 标签必须使用常量初始化器引用字段。

向 Javadoc添加非常量表达式没有多大意义。

起初，人们可能认为最明智的行为是toString在 Javadoc 中添加一个。但是，如果你有一个像这样的可变对象会发生什么：

class MutableInteger {
    public int i;
    public String toString() { return Integer.toString(i); }
}

和一个 Javadoc，如：

/**
 * {@value #obj}
 */
class Class {
    public static final MutableInteger obj = new MutableInteger(0);
}

然后人们可以稍后简单地做：

Class.obj.i = 1;

所以添加0到 Javadoc 没有多大意义。

它仅适用于字符串，因为它们是不可变的，并且 JLS 明确表示：您无法在自定义类上告诉编译器。