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

Question

Je développe une API avec de nombreuses méthodes nommées de manière identique qui diffèrent simplement par la signature, ce que je suppose est assez commun. Ils font tous la même chose, sauf qu'ils initialisent diverses valeurs par défaut si l'utilisateur ne veut pas spécifier. En tant qu'exemple digeste, considérons

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 tous ces procédés 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 qui est 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 magie qui des @params appliquer à chacune des méthodes et générer ainsi de bons documents pour toutes les méthodes à la fois. Avec Javadoc, si je comprends bien, tout ce que je peux faire c'est copier essentiellement & 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 lourd et difficile à maintenir.

Y a-t-il un moyen de contourner cela? Une extension à javadoc qui a ce genre de support? Ou y at-il une bonne raison pour laquelle ce n'est pas soutenu que j'ai manqué?

Answer 1

Je ne connais pas de support, mais, je javadoc complètement la méthode avec le plus d'arguments, et puis se référer à 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) 
*/ 

Answer 2

Je voudrais juste documenter votre méthode « la plus complète » (dans ce cas addTree(int,Fruit,int)), puis dans la JavaDoc pour d'autres méthodes se référer à celui-ci et expliquer comment/qui valeurs par défaut sont utilisées pour les arguments non prévus.

/** 
* 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); 

Answer 3

Il n'y a probablement pas de bonne méthode standard, puisque même le code source JDK9 copier simplement des pâtes de gros morceaux de la documentation autour, 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 commentaire sont répétées. Yikes, non-DRYness.

Answer 4

Placez la documentation sur l'interface, si vous le pouvez. Les classes qui implémentent l'interface hériteront alors de javadoc.

interface X(){ 
/** does fooish things */ 
void foo(); 
} 

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

Si vous voulez hériter de la documentation et d'ajouter vos propres trucs à elle, 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 que je 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, comme décrit par d'autres, ou vous pourriez penser à votre conception.Peut-être que vous souhaitez éviter de surcharger la méthode et utiliser une seule méthode avec un objet de paramètre au lieu, comme ceci:

public Tree addTree(TreeParams p); 

A utiliser comme ceci:

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

Vous aimeriez avoir un regardez ce modèle copie-mutator ici:

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

en fonction de la quantité de combinaisons de paramètres cela pourrait être la façon plus facile et plus propre, puisque la classe Params pourrait capturer les valeurs par défaut et avoir un javadoc pour chaque paramètre.