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 al menos parcialmente un formato común, de forma que los comentarios escritos por un programador resultaran legibles por otro. 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):
package figuras;
/**
* 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
*/
INDICADORES MAS USUALES
- @author nombreDelAutor descripción.
- @version númeroVersión descripción.
- @param nombreParámetro descripción.
- @return descripción.
- @see nombre descripción.
- @throws nombreClaseExcepción descripción.
- @deprecated descripción.
HERRAMIENTA JAVADOC
Aparte de obtenerse comentarios más fáciles de leer para otros programadores debido al formato impuesto por los indicadores, la principal utilidad de estos comentarios es que pueden utilizarse para generar la documentación de los programas. Para ello se utiliza la herramienta javadoc parte de JDSK. El formato más sencillo de esta herramienta, cuando se emplea desde línea de comandos es:javadoc fichero.java Por ejemplo:javadoc Círculo.java Lo que hace esta herramienta es extraer los comentarios JavaDoc contenidos en el programa Java indicado y construir con ellos ficheros .html que puede servir como documentación de la clase. Por ejemplo, esta es el fichero Círculo.html que genera javadoc (entre otros) al procesar el fichero Círculo.java (para distinguirlo de este documento muestro el fondo en color, aunque en realidad es blanco):
No hay comentarios:
Publicar un comentario