Javadoc

Javadoc (parte 1)

JavaDoc. Comentando el código fuente.
Este artículo es el inicio de una serie de ellos dedicados a aprender cómo comentar el código
Java y cómo generar la documentación HTML de nuestras API's mediante la herramienta de
generación automática Javadoc.
Como mi mentor en Java me dijo una vez, el buen código en Java se comenta solo y no le
falta razón. Por eso, aquí vamos a aprenderque no es necesario comentar todas las líneas de
código (salvo algún caso excepcional que requiera ser remarcado por su importancia).
Realmente lo único necesario es comentar la clase y cada uno de los métodos que empleemos,
bien para quien quiera entender qué hace esa clase o la función que desenpeñan cada uno de
los métodos o bien, como es la intención de este artículo para que luego laherramienta de
generación automática de documentación nos cree la nuestra.
En este primer artículo nos dedicaremos a aprender cómo se comentan las clases y las
etiquetas que disponemos para añadir información adicional.

Tipo de comentario para generar la documentación.
A parte de los ya sabidos /* */ ó //, también tenemos un tercero propio de java y que es el que
usa el javadoc como delimitador parareconocer la documentación que tiene que generar.
Cualquier comentario de este tipo debe comenzar por el delimitador /** y, luego, cada línea
de comentario que añadamos debe seguir al operador *. Así mismo, también comenzarán por
un * las etiquetas, sólo que éstas a su vez deben ser precedidas por el operador @ como se
verá en el próximo
capítulo.
Una cosa muy importante que quiero resaltar ya es quejavadoc lo único que hace es copiar el
contenido a una página HTML por lo que se admite cualquier etiqueta HTML que queráis
para darle más claridad o vistosidad a vuestra documentación. Vemos a continuación el
formato típico de un comentario al estilo javadoc.
/**
* Al usar este estilo de comentario estoy consiguiendo que cuando
* lo pase por javadoc, esta herramienta copie este texto a unapágina
* html.
* Puedes ver que también admite etiquetas HTML
* y ésto último que acabo de escribir aparecerá en negrita.
*/

Las etiquetas.
Aparte de los comentarios propios, la utilidad javadoc nos proporciona una serie de etiquetas
para completar la información que queremos dar de una determinada clase o método. Son las
siguientes:
@author nombre (desde la versión 1.0 del JDK/SDK)

1http://www.javahispano.com

Indica el autor de la clase en el argumento nombre. Un comentario de este tipo puede tener
más de un autor en cuyo caso podemos usar tantas etiquetas de este tipo como autores hayan
colaborado en la creación del código fuente o bien podemos ponerlos a todos en una sola
etiqueta. En éste último caso, Javadoc inserta una (,) y un espacio entre los diferentes
nombres.@deprecated comentario (desde la versión 1.0 del JDK/SDK)
Añade un comentario indicando que este API no debería volver a usarse, aunque aun siga
perteneciendo a la distribución del SDK que estemos utilizando, por estar desautorizado o
"desfasado". No obstante, ésto es sólo una advertencia que nosotros damos a los usuarios de
nuestras API's, al igual que las distribuciones de Sun hacen con nosotros.Realmente, lo que
estamos haciendo al decir que una determinada API está desfasada es prevenir de que en un
futuro podrán surgir incompatibilidades si seguimos usándolas ya que éste es el paso a previo
a la desaparición del API en concreto.
En la primera frase del comentario, que es la que la documentación nos la muestra en la
sección del resumen de nuestra clase, deberíamos como mínimo poner desde queversión de
nuestra API está desautorizada y por quién se debería sustituir. A partir de Java 1.2 podemos
usar {@link} para referenciar por quién debemos hacer la sustitución.

@exception nombre-clase descripción (desde la versión 1.0 del JDK/SDK)
Esta etiqueta actúa exactamente igual que @throws.

{@link nombre etiqueta} (desde la versión 1.2 del JDK/SDK)
Inserta un enlace autocontenido que...