Как использовать тег @value в javadoc?

Я использую класс с частным конструктором вместо enum (это требование). И теперь я пытаюсь добавить теги javadoc для документирования каждого объекта public static final.

1) Что такое место для размещения тегов javadoc: например, ob1 или ob2?

2) Оба варианта генерируют ошибку в 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() {}   
}

Ответы

Ответ 1

Я не думаю, что ответ Kayaman достаточно, поскольку вопрос заключается в том, как использовать тег @value в javadocs.

Я думаю, что проблема заключается в том, что значение ссылки на поле не является буквальным значением.

В eclipse, когда вы

/**
 * {@value #ob2} object2 description
 */ 
public static final Object ob2 = new Object();

сгенерированные Javadocs являются {@value # ob2} описанием объекта2. Однако, если у вас есть

/**
 * {@value #ob2} object2 description
 */ 
public static final String ob2 = "hello";

сгенерированные Javadocs являются "hello" object2 description (ожидаемый результат).

Итак, в общем, вы правильно используете тег @value в javadocs, но значение будет отображаться только правильно, если поле было инициализировано литеральным значением.

Ответ 2

2) Оба варианта генерируют ошибку в теге IDEA @value, чтобы ссылаться на поле с постоянным intializer.

Не имеет смысла добавлять непостоянные выражения в Javadoc.

Сначала можно подумать, что самым разумным поведением было бы добавить toString в Javadoc. Но тогда, что произойдет, если у вас есть изменяемый объект, например:

class MutableInteger {
    public int i;
    public String toString() { return Integer.toString(i); }
}

и Javadoc вроде:

/**
 * {@value #obj}
 */
class Class {
    public static final MutableInteger obj = new MutableInteger(0);
}

Затем можно было бы просто сделать следующее:

Class.obj.i = 1;

поэтому добавление 0 в Javadoc не означает многого.

Он работает только для строк, потому что они неизменны, и JLS явно говорит так: нет способа сообщить компилятору, что в пользовательском классе.