Reutilización de Javadoc y métodos sobrecargados

Estoy desarrollando una API con muchos métodos 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 desea especificar. Como ejemplo digerible, considereReutilización de Javadoc y métodos sobrecargados

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. Muchas cosas importantes que los usuarios de mi API necesitan saber sobre cómo agregar árboles se mantienen para todos estos métodos.

Idealmente, me gustaría escribir un bloque de Javadoc que es 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 cuál de los mágicamente @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 copiar básicamente & pegar el mismo bloque 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 evitarlo? ¿Alguna extensión a javadoc que tenga este tipo de soporte? ¿O hay una buena razón por la cual esto no es compatible con lo que perdí?

Fuente

2010-04-01 skrebbel

Gran pregunta y excelente descrito, gracias. –

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

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

Fuente

2010-04-01 07:14:06

Extraño, esto funciona cuando hago referencia al método desde un archivo diferente, pero no desde el mismo archivo (en Eclipse 4.7 en Mac), lo cual es un fastidio cuando intenta desaprobar una sobrecarga y señala a los que llaman a un no- depreciación obsoleta. –

me acaba de documentar su método de "la más completa" (en este caso addTree(int,Fruit,int)) y luego en el Javadoc de otros métodos se refieren a éste y explicar cómo/qué valores por defecto se utilizan para los argumentos no previstos.

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

Fuente

2010-04-01 07:55:07 ArtB

No es probable que ningún buen método estándar, ya que incluso el código fuente JDK9 simplemente copiar pastas de grandes trozos de documentación en torno a, por ejemplo, en:

Se repiten 4 líneas de comentarios. Yikes, no SECADO.

Fuente

2015-01-23 16:19:43

Ponga la documentación en la interfaz, si puede. Las clases que implementan la interfaz heredarán 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 desea heredar la documentación y añadir su propio material a ella, puede utilizar {} @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 he Entendido, esto no es exactamente lo que quiere (desea evitar repeticiones entre los métodos en la misma clase/interfaz). Para esto, puede usar @see o @link, tal como lo describen otros, o puede pensar en su diseño.Tal vez desea evitar la sobrecarga del método y utilizar un único método con un objeto parámetro en lugar, de este modo:

public Tree addTree(TreeParams p);

Para usarse como esto:

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

que le gustaría tener una mira esta copia de patrón-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 que esto podría ser la manera más fácil y más limpio, ya la clase Params podría capturar los valores predeterminados y tener un javadoc para cada parámetro.

Fuente

2016-04-20 09:48:30 Brixomatic

Reutilización de Javadoc y métodos sobrecargados

Respuesta

Cuestiones relacionadas