Réutilisation de Javadoc pour les méthodes surchargées

Question

Je développe une API avec de nombreuses méthodes nommées de manière identique qui ne diffèrent que par leur signature, ce qui est assez courant. Elles font toutes la même chose, sauf qu'elles initialisent différentes valeurs par défaut si l'utilisateur ne souhaite pas les spécifier. Pour donner un exemple concret, considérez

public interface Forest
{
  public Tree addTree();

  public Tree addTree(int amountOfLeaves);

  public Tree addTree(int amountOfLeaves, Fruit fruitType);

  public Tree addTree(int amountOfLeaves, int height);

  public Tree addTree(int amountOfLeaves, Fruit fruitType, int height);
}

L'action essentielle effectuée par toutes ces méthodes est la même : un arbre est planté dans la forêt. De nombreuses informations importantes que les utilisateurs de mon API doivent connaître sur l'ajout d'arbres sont valables pour toutes ces méthodes.

Idéalement, j'aimerais écrire un bloc Javadoc unique utilisé par toutes les méthodes :

  /**
   * Plante un nouvel arbre dans la forêt. Veuillez noter qu'il peut
   * falloir jusqu'à 30 ans pour que l'arbre atteigne sa pleine croissance.
   *
   * @param amountOfLeaves nombre souhaité de feuilles. Le nombre réel de
   * feuilles à maturité peut varier jusqu'à 10%.
   * @param fruitType le type de fruit désiré à cultiver. Aucune garantie
   * n'est donnée quant à la saveur.
   * @param height hauteur souhaitée en centimètres. La hauteur réelle peut
   * varier jusqu'à 15%.
   */

Dans mon imagination, un outil pourrait magiquement choisir quels @params s'appliquent à chacune des méthodes, et donc générer de bons docs pour toutes les méthodes en une seule fois.

Avec Javadoc, si je comprends bien, tout ce que je peux faire est essentiellement de copier-coller le même bloc javadoc cinq fois, avec seulement une liste de paramètres légèrement différente pour chaque méthode. Cela me semble fastidieux, et c'est aussi difficile à maintenir.

Y a-t-il un moyen de contourner cela ? Une extension de Javadoc qui offre ce type de support ? Ou y a-t-il une bonne raison pour laquelle cela n'est pas pris en charge que j'aurais manquée ?

Answer 1

Je ne connais aucun support, mais je documenterais entièrement la méthode avec le plus d'arguments en Javadoc, puis je ferais référence à celle-ci dans une autre Javadoc comme ceci. Je pense que c'est suffisamment clair et évite la redondance.

/**
 * {@code fruitType} par défaut à {@link FruitType#Banana}.
 *
 * @see Forest#addTree(int, Fruit, int)
 */

Answer 2

Je documenterais simplement votre méthode "fullest" (dans ce cas addTree(int,Fruit,int)) et ensuite dans la JavaDoc pour les autres méthodes, je ferais référence à celle-ci et expliquerais comment/quelles valeurs par défaut sont utilisées pour les arguments non fournis.

/**
 * Fonctionne exactement comme {@link ThisClass#myPow(double,double)} sauf que l'exposant est toujours 
 * présumé être 2.
 *
 * @see ThisClass#myPow(double,double)
 */
static double myPow( double base );

Answer 3

Il n'y a probablement pas de bonne méthode standard, puisque même le code source JDK9 se contente de copier-coller de grosses parties de documentation, par exemple, à :

• http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l417
• http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l464

4 lignes de commentaires sont répétées. Oups, non-DRYness.

Answer 4

Placez la documentation à l'interface, si possible. Les classes qui implémentent l'interface hériteront alors du javadoc.

interface X(){
 /** fait des choses fooish */
 void foo();
}

class Ax implements X{ // hérite automatiquement du Javadoc de "X"
 @Override 
 public void foo(){/*...*/} 
}

Si vous souhaitez hériter de la documentation et y ajouter vos propres éléments, vous pouvez utiliser {@inheritDoc} :

class Bx implements X{
 /**
  * {@inheritDoc}
  * Peut échouer avec une RuntimeException, si la machine est trop foo pour être vraie.
  */
 @Override 
 public void foo(){/*...*/}
}

Voir aussi : http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments

A présent, si j'ai bien compris, ce n'est pas exactement ce que vous voulez (vous voulez éviter les répétitions parmi les méthodes dans la même classe/interface). Pour cela, vous pouvez utiliser @see ou @link, comme décrit par d'autres, ou vous pouvez réfléchir à votre conception. Peut-être préféreriez-vous éviter la surcharge de la méthode et utiliser une seule méthode avec un objet de paramètres à la place, comme ceci :

public Tree addTree(TreeParams p);

À utiliser de cette manière :

forest.addTree(new TreeParams().with(Fruits.APPLE).withLeaves(1500).withHeight(5));

Vous voudrez peut-être jeter un œil à ce modèle de copie-mutateur ici :

https://brixomatic.wordpress.com/2010/03/10/dealing-with-immutability-and-long-constructors-in-a-fluent-way/

En fonction du nombre de combinaisons de paramètres, cela pourrait être plus facile et plus propre, car la classe Params pourrait capturer les valeurs par défaut et avoir un javadoc pour chaque paramètre.