Reutilización de Javadoc para métodos sobrecargados

Estoy desarrollando una API con muchos métodos con nombres idénticos que solo difieren en la firma, lo que supongo que es bastante común. Todos hacen lo mismo, excepto que inicializan varios valores por defecto si el usuario no quiere especificar. Como un ejemplo digerible, considere

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);
}

La acción esencial realizada por todos estos métodos es la misma; un árbol está plantado en el bosque. Hay muchas cosas importantes que los usuarios de mi API deben saber acerca de cómo agregar árboles para todos estos métodos.

Idealmente, me gustaría escribir un bloque Javadoc que sea utilizado por todos los métodos:

  /**
   * 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%.
   */

En mi imaginación, una herramienta podría elegir mágicamente cuál de los @params se aplica a cada uno de los métodos y, por lo tanto, generar buenos documentos para todos los métodos a la vez.

Con Javadoc, si lo entiendo correctamente, todo lo que puedo hacer es esencialmente copiar y pegar el mismo bloque de javadoc cinco veces, con solo una lista de parámetros ligeramente diferente para cada método. Esto me parece engorroso y también es difícil de mantener.

¿Hay alguna forma de evitar eso? ¿Alguna extensión para javadoc que tenga este tipo de soporte? ¿O hay una buena razón por la que esto no es compatible que me perdí?

No conozco ningún soporte, pero haría un javadoc completo con el método con la mayoría de los argumentos, y luego me referiría a él en otro javadoc como ese. Creo que es lo suficientemente claro y evita la redundancia.

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

Simplemente documentaría su método “más completo” (en este caso addTree(int,Fruit,int) ) y luego en JavaDoc para otros métodos, consulte este y explique cómo/qué valores predeterminados se usan para los argumentos no proporcionados.

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

Es probable que no exista un buen método estándar, ya que incluso el código fuente de JDK9 simplemente copia y pega grandes porciones de documentación, por ejemplo, en:

• 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

Se repiten 4 líneas de comentario. Vaya, no sequedad.

Ponga la documentación en la interfaz, si puede. Las clases que implementan la interfaz heredarán el javadoc.

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

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

En caso de que desee heredar la documentación y agregarle sus propias cosas, puede usar {@inheritDoc}:

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

Ver también:
http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments

Ahora, como entendí, esto no es exactamente lo que desea (desea evitar repeticiones entre los métodos en la misma clase/interfaz). Para esto, puede usar @see o @link, como lo describen otros, o puede pensar en su diseño. Tal vez le gustaría evitar sobrecargar el método y usar un solo método con un objeto de parámetro en su lugar, así:

public Tree addTree(TreeParams p);

Para ser usado así:

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

Es posible que desee echar un vistazo a este patrón de copia-mutador aquí:

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

Dependiendo de la cantidad de combinaciones de parámetros, esta podría ser la forma más fácil y limpia, ya que Params-Class podría capturar los valores predeterminados y tener un javadoc para cada parámetro.