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

Je développe une API avec de nombreuses méthodes portant des noms identiques, mais qui diffèrent par leur signature, ce qui, je suppose, est assez courant. Ils font tous la même chose, sauf qu’ils initialisent différentes valeurs par défaut si l’utilisateur ne veut pas spécifier. Comme exemple digeste, 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. Beaucoup de choses importantes que les utilisateurs de mon API doivent savoir sur l’ajout d’arbres sont valables pour toutes ces méthodes.

Idéalement, je voudrais écrire un bloc Javadoc utilisé par toutes les méthodes:

  /** * Plants a new tree in the forest. Please note that it may take * up to 30 years for the tree to be fully grown. * * @param amountOfLeaves desired amount of leaves. Actual amount of * leaves at maturity may differ by up to 10%. * @param fruitType the desired type of fruit to be grown. No warranties * are given with respect to flavour. * @param height desired hight in centimeters. Actual hight may differ by * up to 15%. */ 

Dans mon imagination, un outil peut choisir comme par magie lequel des @params s’applique à chacune des méthodes, et ainsi générer de bons documents pour toutes les méthodes à la fois.

Avec Javadoc, si je comprends bien, je ne peux que copier et coller le même bloc javadoc cinq fois, avec une liste de parameters légèrement différente pour chaque méthode. Cela me semble lourd et difficile à maintenir.

Y a-t-il un moyen de contourner cela? Une extension à javadoc qui a ce genre de support? Ou existe-t-il une bonne raison pour laquelle cela n’a pas été pris en charge?

Je ne connais aucun support, mais je javadoc entièrement la méthode avec le plus d’arguments, puis je me réfère à lui dans d’autres javadoc comme ça. Je pense que c’est suffisamment clair et évite la redondance.

 /** * {@code fruitType} defaults to {@link FruitType#Banana}. * * @see Forest#addTree(int, Fruit, int) */ 

Je voudrais juste documenter votre méthode “la plus complète” (dans ce cas, addTree(int,Fruit,int) ), puis dans le JavaDoc pour les autres méthodes se référer à celle-ci et expliquer comment / quelles valeurs par défaut sont utilisées pour les arguments non fournis.

 /** * Works just like {@link ThisClass#myPow(double,double)} except the exponent is always * presumed to be 2. * * @see ThisClass#myPow(double,double) */ static double myPow( double base ); 

Il n’y a probablement pas de bonne méthode standard, car même le code source JDK9 ne fait que copier de gros morceaux de documentation, par exemple à:

4 lignes de commentaire sont répétées. Yikes, non-DRYness.

Mettez la documentation à l’interface, si vous le pouvez. Les classes qui implémentent l’interface hériteront alors du javadoc.

 interface X(){ /** does fooish things */ void foo(); } class Ax implements X{ //automatically inherits the Javadoc of "X" @Override public void foo(){/*...*/} } 

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

 class Bx implements X{ /** * {@inheritDoc} * May fail with a RuntimeException, if the machine is too foo to be true. */ @Override public void foo(){/*...*/} } 

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

Maintenant, comme je l’ai compris, ce n’est pas exactement ce que vous voulez (vous voulez éviter les répétitions parmi les méthodes de la même classe / interface). Pour cela, vous pouvez utiliser @see ou @link, tel que décrit par d’autres, ou bien penser à votre conception. Vous voudrez peut-être éviter de surcharger la méthode et utiliser une méthode unique avec un object paramètre, comme ceci:

 public Tree addTree(TreeParams p); 

Pour être utilisé comme ceci:

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

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

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

Selon la quantité de combinaisons de parameters, cela pourrait être la méthode la plus simple et la plus propre, car la classe Params pourrait capturer les valeurs par défaut et disposer d’un javadoc pour chaque paramètre.