Fundamentos básicos de la herramienta javadoc

1. PROGRAMACIÓN I
JAVADOC

2. Comentarios en Java
● Los comentarios, anotaciones en el código que
el compilador ignora pero son útiles para los
programadores, existen en los lenguajes de
programación desde el principio.
● Desde hace mucho tiempo se observó que en
realidad los comentarios se usaban para dos
propósitos diferentes:

3. Comentarios en Java
● Para explicar el propósito de una o varias sentencias.
Estos comentarios son útiles para el propio autor del
código, y para otros que quieran modificar ese código.
● Comentarios explicando qué hace una "pieza" cerrada de
código. Estos comentarios son útiles para quien quiere
utilizar esta "pieza" en su propio programa, y que por tanto
está necesita saber lo qué hace, no cómo se las ha
arreglado el programador para conseguir este resultado.

4. Comentarios en Java
● Al diseñar Java se distinguieron desde el principio
ambas posibilidades.
● Para el primer tipo, comentarios "internos" se usan los
caracteres // o /* */:
// esto es un comentario
/* esto también
es un comentario */

5. Comentarios en Java
● El segundo tipo, los usados para explicar qué hace un
código son los llamados en Java comentarios
JavaDoc, y se escriben comenzando por /** y
terminando con */ , pudiendo ocupar varias líneas.
● Mientras que los comentarios usuales no tienen
ningún formato, los comentarios JavaDoc siguen una
estructura prefijada que describimos en el siguiente
apartado.

6. Formato de JavaDoc
● Los comentarios JavaDoc están destinados a
describir, principalmente, clases y métodos.
● Como están pensados para que otro programador los
lea y utilice la clase (o método) correspondiente, se
decidió fijar un formato común, de forma que los
comentarios escritos por un programador resultaran
legibles por otro.

7. Formato de JavaDoc
● Para ello los comentarios JavaDoc deben incluir unos
indicadores especiales, que comienzan siempre por
@ y se suelen colocar al comienzo de línea. Por
ejemplo esta es una clase para representar números
círculos (reducida al mínimo):

8. Comentando una clase
/**
* Una clase para representar círculos situados sobre el plano.
* Cada círculo queda determinado por su radio junto con las
* coordenadas de su centro.
* @version 1.2, 24/12/04
* @author Rafa Caballero
*/

9. Comentando un método
/**
* Cálculo del área del círculo.
* @param radio de la circunferencia
* @return El área (mayor o igual que 0) del círculo.
*/
public double área(double r) {
return Math.PI*r*r;
}

10. Conclusión
● Un programa mal documentado es, básicamente, un
programa inútil. Los programas no son nunca productos
cerrados, acabados; siempre se encuentran errores que
corregir, posibles ampliaciones.
● El código que nos parece evidente un día se convierte
en críptico una semana después.
● La herramienta javadoc ayuda a mantener la
documentación del código en un formato legible y
práctico.