How to use @value tag in javadoc?

Question

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 or ob2?

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

Try using non-IDEA specific javadoc. Unless this is somehow in the javadoc spec and I haven't heard of it... You can leave the whole @value part out. — Kayaman, Nov 06 '13 at 09:01
@value is not IDEA specific. Introduced in 1.4, http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#value — JamesB, Nov 06 '13 at 09:25
Yes, I know @value isn't IDEA specific, however I've seen it in method javadocs only. If you just enter the description next to the field it should generate correctly (and hopefully without error). — Kayaman, Nov 06 '13 at 09:27

score 38 · Answer 1 · answered Nov 06 '13 at 15:03

38

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.

answered Nov 06 '13 at 15:03

JamesB

7,774
2
22
21

9

To 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. – Javaru Nov 06 '13 at 19:07
3

I fixed a similar error in my project by changing the `@value` to an `@link`. – Andrew Swan Apr 10 '15 at 02:42
1

Worth noting that you can _only_ use `@value` within the same class (i.e. FQN prefixes before the `#` won't work) – earcam Nov 23 '18 at 19:10
@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. – DavidS Oct 13 '19 at 16:05

Ciro Santilli OurBigBook.com · Answer 2 · 2015-12-13T00:52:45.653

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.

Does this only work for constant values? – Flimtix Jun 01 '22 at 09:15 — Flimtix, Jun 01 '22 at 09:15

How to use @value tag in javadoc?

2 Answers2