llama - Reutilización de Javadoc y métodos sobrecargados.
javadoc pdf (4)
Es probable que no haya 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. Yikes, no DRYness.
Estoy desarrollando una API con muchos métodos con nombres idénticos que solo difieren por firma, que creo 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 digestible, 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 de las cosas importantes que los usuarios de mi API deben saber acerca de agregar árboles tienen para todos estos métodos.
Idealmente, me gustaría escribir un bloque Javadoc que utilizan 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 javadoc cinco veces, con solo una lista de parámetros ligeramente diferente para cada método. Esto me suena incómodo y también es difícil de mantener.
¿Hay alguna manera 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 está respaldado y lo perdí?
No conozco ningún tipo de apoyo, pero yo javadoc sería el método con la mayoría de los argumentos, y luego me referiría a él en otros javadoc de esta manera. Creo que es suficientemente claro, y evita la redundancia.
/**
* {@code fruitType} defaults to {@link FruitType#Banana}.
*
* @see Forest#addTree(int, Fruit, int)
*/
Pon la documentación en la interfaz, si puedes. 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 quiera heredar la documentación y agregarle su propio material, 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(){/*...*/}
}
Consulte también: http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments
Ahora como lo entendí, esto no es exactamente lo que quieres (quieres evitar repeticiones entre los métodos en la misma clase / interfaz). Para esto puede usar @see o @link, como lo describen otros, o podría 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 de esta manera:
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í:
Dependiendo de la cantidad de combinaciones de parámetros, esta podría ser la forma más fácil y limpia, ya que la Clase Params podría capturar los valores predeterminados y tener un javadoc para cada parámetro.
Solo documentaría su método "más completo" (en este caso addTree(int,Fruit,int) ) y luego en el JavaDoc para otros métodos, refiérase a éste 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 );