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

Answer 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.

Answer 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.