How to use @value tag in javadoc?
Solution 1
I don't think Kayaman's answer is sufficient as the question is how to use the @value tag in javadocs.
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
/**
* {@value #ob2} object2 description
*/
public static final String ob2 = "hello";
the generated Javadocs are "hello" object2 description (the expected output).
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.
Solution 2
2) Both options generate error in IDEA @value tag must reference field with a constant intializer.
It does not make much sense to add non-constant expressions to the 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:
class MutableInteger {
public int i;
public String toString() { return Integer.toString(i); }
}
and a Javadoc like:
/**
* {@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.
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.
Nikolay Kuznetsov
Updated on December 13, 2020Comments
-
Nikolay Kuznetsov over 3 years
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.1) What is prefered place to put javadoc tags: like
ob1
orob2
?2) Both options generate error in 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() {} }
-
Javaru over 10 yearsTo add to @JamesB answer, the value the
@value
parameter references has to be a constant (i.e. static and final) and be of a type that has a constant initializer. In general, this means Strings and primitives. -
juckele about 9 yearsI fixed a similar error in my project by changing the
@value
to an@link
. -
earcam over 5 yearsWorth noting that you can only use
@value
within the same class (i.e. FQN prefixes before the#
won't work) -
DavidS over 4 years@earcam The Netbeans Javadoc tab resolves the \@value tag even with prefixes before the #. Possibly other IDEs do as well. Maybe the actual Javadoc tool (html generation) doesn't resolve them though -- I didn't test this.
-
Flimtix almost 2 yearsDoes this only work for constant values?