web-dev-qa-db-fra.com

Comment écrire Javadoc de propriétés?

Je me trouve souvent confronté à un dilemme lors de l'écriture de javadoc pour les propriétés/membres d'une "simple" classe POJO ne contenant que des propriétés, des getters et des setters (style DTO) ....

1) Ecrire javadoc pour la propriété
ou...
2) Écrivez javadoc pour le getter

Si j'écris javadoc pour la propriété, mon IDE (Eclipse) ne sera (naturellement) pas en mesure de l'afficher lorsque j'aurai plus tard accès au POJO via la complétion de code. Et il n'y a pas de balise javadoc standard qui me permet de relier le getter-javadoc à la propriété réelle javadoc.

Un exemple:

public class SomeDomainClass {

  /**
   * The name of bla bla bla
   */
  private String name;

  /**
   * @return INSERT SOME SMART JAVADOC TAG LINKING TO name's javadoc
   */
  public String getName() {  
    return name;  
  }

Donc, en gros, il serait intéressant d’entendre comment d’autres personnes se servent de votre Eclipse IDE) pour afficher la description de la propriété javadoc de vos getters - sans avoir à dupliquer le commentaire javadoc.

À partir de maintenant, j'envisage de faire en sorte que ma pratique soit de documenter uniquement les accesseurs, et non les propriétés. Mais cela ne semble pas être la meilleure solution ...

javajavadoc
86
user274360

Vous pouvez inclure des membres privés lors de la génération de Javadocs (avec -private), puis utiliser @link pour créer un lien vers cette propriété de champs.

public class SomeDomainClass {
    /**
     * The name of bla bla bla
     */
    private String name;

    /**
     * {@link SomeDomainClass#name}
     */
    public String getName() {
        return name;
    }
}

Sinon, si vous ne souhaitez pas générer la Javadoc pour tous les membres privés, vous pouvez avoir une convention pour documenter tous les getters et utiliser @link sur les setters.

public class SomeDomainClass {
    private String name;

    /**
     * The name of bla bla bla
     */
    public String getName() {
        return name;
    }

    /**
     * {@link SomeDomainClass#getName}
     */
    public void setName(String name) {
        this.name = name;
    }
}
71
Chandra Sekar

Je fais les deux, avec l'aide de la saisie semi-automatique d'Eclipse.

Tout d'abord, je documente la propriété:

/**
 * The {@link String} instance representing something.
 */
private String someString;

Ensuite, je copie et colle ceci dans le getter:

/**
 * The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Avec Eclipse, les instructions @return ont une autocomplétion. J'ajoute donc le mot Gets, le "t" en minuscule et copie la phrase avec le "t" en minuscule. J'utilise ensuite @return (avec Eclipse autocomplete), colle la phrase, puis majuscule le T dans la déclaration. Cela ressemble alors à ceci:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Enfin, je copie cette documentation sur le poseur:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Ensuite, je le modifie et avec Eclipse autocomplete, vous pouvez obtenir non seulement la balise @param mais également le nom du paramètre:

/**
 * Sets the {@link String} instance representing something.
 * @param someString The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Ensuite, j'ai fini. À mon avis, ce modèle facilite beaucoup, à long terme, non seulement de vous rappeler ce que la propriété signifie par répétition, mais il est également plus facile d'ajouter des commentaires supplémentaires au getter et au setter si vous souhaitez ajouter un côté. effets (par exemple, ne pas autoriser les propriétés NULL, convertir les chaînes en majuscules, etc.). J'ai étudié la possibilité de créer un plug-in Eclipse à cette fin, mais je ne pouvais pas trouver le point d'extension approprié pour le JDT, alors j'ai abandonné.

Notez que la phrase peut ne pas toujours commencer par un T - c'est simplement que la première lettre doit être décapitalisée/recapitalisée lors du collage.

3
MetroidFan2002

Lombok est une bibliothèque très pratique pour de telles tâches.

@Getter
@Setter
public class Example {
    /**
     * The account identifier (i.e. phone number, user name or email) to be identified for the account you're
     * requesting the name for
     */
    private String name;
}

C'est tout ce dont vous avez besoin! Le @Getter annotation crée une méthode de lecture pour chaque champ privé et y attache le javadoc.

[~ # ~] ps [~ # ~] : La bibliothèque propose de nombreuses fonctionnalités intéressantes que vous voudrez peut-être utiliser.

2
Amanuel Nega

Je pense vraiment que c'est un problème et que le document officiel Guide Javadoc n'en dit rien. C # peut résoudre ce problème de manière élégante avec l'utilisation de Properties (je ne code pas en C #, mais je pense vraiment que c'est une fonctionnalité intéressante).

Mais je suppose: si vous avez besoin d’expliquer ce que someString est, c’est peut-être un "mauvais petit" sur votre code. Cela peut signifier que vous devriez écrire SomeClass pour saisir someString, de sorte que vous expliqueriez ce qu'est someString dans la documentation de SomeClass et que les javadocs dans getter/setter ne sont pas nécessaires.

0
Leonardo Leite