How to use @value tag in javadoc?

Nikolay Kuznetsov picture Nikolay Kuznetsov · Nov 6, 2013 · Viewed 34k times · Source

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

JamesB picture JamesB · Nov 6, 2013

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.