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

I am using a class with private constructor instead of an enum (this is a requirement). And now I am trying to add javadoc tags to document each public static final entity.

我正在使用一个私有构造函数而不是枚举的类(这是一个要求)。现在我正在尝试添加javadoc标记来记录每个公共静态最终实体。

1) What is prefered place to put javadoc tags: like ob1 or ob2?

1)放置javadoc标签的首选位置是什么:像ob1或ob2?

2) Both options generate error in IDEA @value tag must reference field with a constant intializer.

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

/**
 * {@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() {}   
}

2 个解决方案

#1

I don't think Kayaman's answer is sufficient as the question is how to use the @value tag in javadocs.

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

I think the problem lies in the fact that the value of the field being referenced is not a literal value.

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

In eclipse, when you have

在日食中,当你有

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

the generated Javadocs are {@value #ob2} object2 description. However, when you have

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

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

the generated Javadocs are "hello" object2 description (the expected output).

生成的Javadocs是“hello”object2 description(预期输出)。

So, in summary, you are using the @value tag correctly in the javadocs but the value will only be rendered correctly if the field has been initialised with a literal value.

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

#2

2) Both options generate error in IDEA @value tag must reference field with a constant intializer.

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

It does not make much sense to add non-constant expressions to the Javadoc.

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

At first, one might think that the most sensible behavior would be to add a toString to the Javadoc. But then, what happens if you had a mutable object like:

首先,人们可能会认为最明智的行为是将一个toString添加到Javadoc。但是,如果您有一个可变对象,会发生什么:

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

and a Javadoc like:

和Javadoc一样:

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

Then one could simply do later on:

然后人们可以稍后再做:

Class.obj.i = 1;

so adding 0 to the Javadoc wouldn't mean much.

所以向Javadoc添加0并不意味着什么。

It only works for strings because they are immutable and the JLS explicitly says so: there is no way for you to tell the compiler that on a custom class.

它只适用于字符串,因为它们是不可变的,JLS明确地这样说:没有办法告诉编译器在自定义类上。

#1