web-dev-qa-db-fra.com

Javadoc réutilisation pour et méthodes surchargées

Je développe une API avec de nombreuses méthodes portant le même nom et ne différant que par la signature, ce qui est assez courant, je suppose. 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 digestible, 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 réalisée par toutes ces méthodes est la même; un arbre est planté dans la forêt. De nombreuses choses importantes que les utilisateurs de mon API doivent savoir sur l’ajout d’arbres à toutes ces méthodes.

Idéalement, j'aimerais é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 pourrait choisir, comme par magie, parmi les @params s’appliquer à chacune des méthodes, et générer ainsi de bonnes documentations pour toutes les méthodes à la 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 lourd et difficile à maintenir.

Y a-t-il un moyen de contourner cela? Une extension du javadoc qui a ce genre de support? Ou y a-t-il une bonne raison pour que ceci ne soit pas pris en charge que j'ai manquée?

javajavadoc
65
skrebbel

Je ne connais aucun support, mais javadoc serait la méthode avec le plus grand nombre d'arguments, puis j'y ferais référence dans d'autres javadoc, comme ça. Je pense que c'est suffisamment clair et évite les redondances.

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

Je voudrais simplement documenter votre méthode "la plus complète" (dans ce cas, addTree(int,Fruit,int)), puis dans 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 );
8
ArtB

Il n’existe probablement pas de bonne méthode standard, car même le code source de JDK9 copie simplement de gros morceaux de documentation, par exemple à:

4 lignes de commentaires sont répétées. Beurk, non-sécheresse.

4
Ciro Santilli 新疆改造中心 六四事件 法轮功

Placez la documentation sur l'interface, si vous le pouvez. Les classes qui implémentent l'interface hériteront 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 ajouter 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

Si j'ai bien compris, ce n'est pas exactement ce que vous voulez (vous voulez éviter les répétitions entre 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. Vous voudrez peut-être éviter de surcharger la méthode et utiliser une seule méthode avec un objet 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 coup d'œ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 la méthode la plus simple et la plus propre, car la classe Params-Class pourrait capturer les valeurs par défaut et disposer d'un javadoc pour chaque paramètre.

0
Brixomatic