Comment utiliser la balise @value dans javadoc?

Question

J'utilise une classe avec un constructeur privé au lieu d'une énumération (c'est une exigence). Et maintenant, j'essaie d'ajouter des balises javadoc pour documenter chaque public static final entité.

1) Quel est l'endroit préféré pour mettre des balises javadoc: comme ob1 ou ob2?

2) Les deux options génèrent une erreur dans 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

Je ne pense pas que la réponse de Kayaman soit suffisante car la question est de savoir comment utiliser la balise @value dans javadocs.

Je pense que le problème réside dans le fait que la valeur du champ référencé n'est pas une valeur littérale.

Dans Eclipse, quand vous avez

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

les Javadocs générés sont {@ value # ob2} description object2. Cependant, lorsque vous avez

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

les Javadocs générés sont "bonjour" description object2 (la sortie attendue).

Donc, en résumé, vous utilisez correctement la balise @value dans les javadocs mais la valeur ne sera rendue correctement que si le champ a été initialisé avec une valeur littérale.

Answer 2

2) Les deux options génèrent une erreur dans IDEA @value doit référencer le champ avec un initialiseur constant.

Cela n'a pas beaucoup de sens d'ajouter expressions non constantes à la Javadoc.

Au début, on pourrait penser que le comportement le plus sensé serait d'ajouter un toString au Javadoc. Mais alors, que se passe-t-il si vous avez un objet mutable comme:

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

et un Javadoc comme:

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

Ensuite, on pourrait simplement faire plus tard:

Class.obj.i = 1;

donc en ajoutant 0 au Javadoc ne signifierait pas grand-chose.

Cela ne fonctionne que pour les chaînes car elles sont immuables et le JLS le dit explicitement: il n'y a aucun moyen pour vous de le dire au compilateur sur une classe personnalisée.