Reutilización de Javadoc para métodos sobrecargados

Question 1

Estoy desarrollando una API con muchos métodos con nombres idénticos que solo se diferencian por la firma, 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 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; se planta un árbol en el bosque. Muchas cosas importantes que los usuarios de mi API deben saber sobre cómo agregar árboles se mantienen 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 así 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 suena engorroso y también es difícil de mantener.

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

Question 2

No conozco ningún soporte, pero, javadoc completamente 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)
 */

Question 3

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

Question 4

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

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

Question 5

Coloque 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(){/*...*/}
}

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

Ahora, según 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 utilizado 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.