Comment écrire Javadoc de propriétés?

Je me trouve souvent face à un dilemme lors de l'écriture de javadoc pour les 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 javadoc pour la propriété
ou ...
2) Ecrire javadoc pour le getter

Si j'écris javadoc pour la propriété, mon IDE (Eclipse) ne pourra (naturellement) pas l'afficher lorsque j'accéderai plus tard au POJO via la complétion de code. Et il n'y a pas de balise javadoc standard qui me permette de lier 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, fondamentalement, il serait intéressant d'entendre comment les autres procèdent pour que votre Eclipse IDE affiche la description de la propriété javadoc pour vos getters - sans avoir à dupliquer le commentaire javadoc.

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

Vous pouvez inclure des membres privés lors de la génération de Javadocs (en utilisant -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 le 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;
    }
}

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! L' @Getterannotation crée une méthode getter pour chaque champ privé et y attache le javadoc.

PS : la bibliothèque a de nombreuses fonctionnalités intéressantes que vous voudrez peut-être acheter

Je fais les deux, aidé par 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 saisie semi-automatique - donc, j'ajoute le mot Gets, minuscule le "t" et copie la phrase avec le "t" minuscule. J'utilise ensuite @return (avec la saisie semi-automatique Eclipse), collez la phrase, puis mettez le T en majuscule dans le retour. 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 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 la saisie semi-automatique 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;
}

Ensuite, j'ai terminé. À mon avis, ce modèle rend beaucoup plus facile, à long terme, non seulement de vous rappeler ce que signifie la propriété par la répétition, mais aussi il est plus facile d'ajouter des commentaires supplémentaires au getter et au setter si vous souhaitez ajouter un côté effets (comme ne pas autoriser les propriétés nulles, transformer les chaînes en majuscules, etc.). J'ai étudié la création d'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 peut ne pas toujours commencer par un T - c'est juste la première lettre qui doit être non capitalisée / recapitalisée lors du collage.

Je pense vraiment que c'est un problème et le guide officiel Javadoc ne dit rien à ce sujet. C # peut résoudre cela 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 supposition: si vous avez besoin d'expliquer ce qu'est someString, c'est peut-être un `` mauvais petit '' à propos de votre code. Cela peut signifier que vous devriez écrire SomeClass pour taper someString, donc vous expliqueriez ce qu'est someString dans la documentation SomeClass, et juste pour que les javadocs dans getter / setter ne soient pas nécessaires.