Comment écrire la Javadoc des propriétés ?

Question

Je me retrouve souvent face à un dilemme lorsque je rédige la javadoc des propriétés/membres d'une classe POJO "simple" ne contenant que des propriétés et des getters et setters (style DTO).....

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

Si j'écris une javadoc pour la propriété, mon IDE (Eclipse) ne sera (naturellement) pas en mesure de l'afficher lorsque j'accéderai ultérieurement au POJO via la complétion de code. Et il n'y a pas de balise javadoc standard qui me permette de lier la javadoc du getter à la javadoc réelle de la propriété.

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 de savoir comment les autres s'y prennent pour que l'IDE Eclipse affiche la description de la propriété javadoc pour vos getters - sans avoir à dupliquer le commentaire javadoc.

Pour l'instant, j'envisage de prendre l'habitude de ne documenter que les getters et non les propriétés. Mais cela ne semble pas être la meilleure solution...

Answer 1

Vous pouvez inclure des membres privés lors de la génération de Javadocs (en utilisant -private) et ensuite utiliser @link pour créer un lien vers la propriété de ce champ.

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

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

Alternativement, si vous ne voulez 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;
    }
}

Answer 2

Lombok est une bibliothèque très pratique pour ce genre de 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 site @Getter L'annotation crée une méthode getter pour chaque champ privé et y attache la javadoc.

PS : La bibliothèque possède de nombreuses fonctionnalités intéressantes que vous pourriez vouloir vérifier.

Answer 3

Je fais les deux, aidé par l'autocomplétion d'Eclipse.

D'abord, je documente la propriété :

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

Ensuite, je copie et colle ceci au getter :

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

Avec Eclipse, les déclarations @return ont une autocomplétion - donc, j'ajoute le mot Gets, je mets le "t" en minuscule, et je copie la phrase avec le "t" en minuscule. J'utilise ensuite @return (avec l'autocomplétion d'Eclipse), je colle la phrase, puis je mets le T en majuscule dans le return. 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 dans le setter :

/**
 * 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 l'autocomplétion d'Eclipse, vous pouvez obtenir non seulement la balise @param mais aussi 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;
}

Alors, j'ai fini. À mon avis, cette modélisation facilite grandement, à long terme, non seulement le rappel de la signification de la propriété par la répétition, mais aussi l'ajout de commentaires supplémentaires aux getter et setter si vous souhaitez ajouter des effets secondaires (comme l'interdiction des propriétés nulles, la mise en majuscules des chaînes de caractères, etc.) J'ai essayé de créer un plugin Eclipse à cet effet, mais je n'ai pas trouvé le point d'extension approprié pour le JDT, alors j'ai abandonné.

Notez que la phrase ne commence pas toujours par un T - c'est juste la première lettre qui doit être non capitalisée/recapitalisée lors du collage.

Answer 4

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

Mais j'ai une idée : si vous avez besoin d'expliquer ce qu'est someString, c'est peut-être un "mauvais petit" de votre code. Cela peut signifier que vous devriez écrire SomeClass pour le type someString, ainsi vous expliqueriez ce qu'est someString dans la documentation de SomeClass, et juste pour que les javadocs dans getter/setter ne soient pas nécessaires.