javadoc @value annotation issue in Eclipse

问题

I've read a lot here but didn't find the answer. I faced a problem with a @value Javadoc annotation.

IDE: Eclipse Oxygen.1a Release (4.7.1a)

If I place it on the String variable it is ok and works properly, but if the variable is Integer then everything is bad.

Here is a code where variables stand side by side:

/**
 * Default delimiter. {@value #DEFAULT_LIST_SEPARATOR}
 */
public final static String DEFAULT_LIST_SEPARATOR = ",";

/**
 * Default int value. {@value #START_VALUE}
 */
public final static Integer START_VALUE = 20000;

and for the first variable description shows properly, but for the other, I see only {@value #START_VALUE}.

Where am I wrong, guys?

回答1:

If Integer instead of int is used, @value is not resolved.

In your example, the constant START_VALUE is an object of the type Integer which wraps the value 20000. So the question is, does @value support autoboxing? The Java Language Specification does not cover Javadoc comments. There seems to be no formal specification for Javadoc, just the following simple description for @value which does not answer the question:

Displays constant values.

If using the the Javadoc tool of the Oracle Java SDK to generate HTML as de facto standard, @value is allowed for int, but not for the type Integer. The Javadoc tools of Oracle's Java 8 and Java 9 Development Kit report the same error:

error: value does not refer to a constant
   * Default int value. {@value #START_VALUE}
                        ^

If using {@value} instead of {@value #START_VALUE} the error becomes error: {@value} not allowed here.

Let's have a look at following cases:

public class JavadocValue {

    /** STRING = {@value} */
    public final static String STRING = "lorem ipsum";

    /** STRING_CONCATENATION = {@value} */
    public final static String STRING_CONCATENATION = "lorem" + " ipsum";

    /** STRING_COMPUTATION = {@value} */
    public final static String STRING_COMPUTATION = System.getProperty("path.separator");

    /** INT = {@value} */
    public final static int INT = 42;

    /** INT_COMPUTATION = {@value} */
    public final static int INT_COMPUTATION = (20 + 1) * 2;

    /** INTEGER = {@value} */
    public final static Integer INTEGER = 42;

    /** INTEGER_COMPUTATION = {@value} */
    public final static Integer INTEGER_COMPUTATION = Integer.valueOf("42");

    /** ENUM = {@value} */
    public final static MyEnum ENUM = MyEnum.VALUE_B;
    public enum MyEnum { VALUE_A, VALUE_B };

}

In Eclipse @value is resolved as it is in the Oracle Javadoc tool:

STRING = "lorem ipsum"
STRING_CONCATENATION = "lorem ipsum"
STRING_COMPUTATION = [error/unresolved]
INT = 42
INT_COMPUTATION = 42
INTEGER = [error/unresolved]
INTEGER_COMPUTATION = [error/unresolved]
ENUM = [error/unresolved]

Conclusion: Use @value for constants of a primitive type or of String only.

回答2:

With Intellij IDEA 2017.2.6 code above works fine:

So, it may be just eclipse bug.

回答3:

Do a clean project and an eclipse restart :) it may work well after these :)

来源：https://stackoverflow.com/questions/47480314/javadoc-value-annotation-issue-in-eclipse

标签

java

eclipse

javadoc