Javadoc - ¿Que es el Javadoc? - ¿Como utilizar el Javadoc? - Indicadores en Javadoc - Tipos de indicadores Javadoc - ¿Donde utilizar Javadoc?

Buenas, hoy vamos hablar un poco del Javadoc, hace un tiempo atrás puse un link en este blog como generar el Javadoc, pero no que es y lo básico de el, tips generales. Bueno ante todo les voy a contar que muchos, pero muchos los voy a tener como enemigos ya que creen que el Javadoc es algo innecesario.

Bueno empecemos comentando que es el Javadoc, para finalmente entiendan mi humilde punto de vista.

¿Que es el Javadoc?

Javadoc es la herramienta de java para generar documentación básica para el programador a partir del código fuente. Se intenta evitar que la documentación que se genera mediante un editor de texto se quede rápidamente obsoleta cuando el programa continúa su desarrollo y no se tiene la disciplina/tiempo para mantener la documentación al día. Para ello, se pide a los programadores de Java que escriban la documentación básica (clases, métodos, etc.) en el propio código fuente (en comentarios en el propio código), con la esperanza de que esos comentarios sí se mantengan actualizados cuando se cambia el código. La herramienta Javadoc extrae dichos comentarios y genera con ellos un juego de documentación en formato html.

Lo interesante de la herramienta (de ahí mi comentario sobre lo extensible de java) es que la transformación fuente->html la realiza utilizando un mecanismo extensible llamado doclet.

En futuros post hablaremos mas que es un doclet, mi fin no es marearlos.


Básicamente javadoc es un programa, que toma lo comentarios que se colocan en el código con marcas especiales y construye un archivo HTML con clases, métodos y la documentación que corresponde. Este HTML tiene el formato de toda la documentación estándar de Java provista por Sun.

Un ejemplo de ello:

¿Como utilizar el Javadoc? 

La documentación a ser utilizada por javadoc se escribe en comentarios que comienzan con /** (notar el doble *) y que terminan con */. A la vez, dentro de estos comentarios se puede escribir código HTML y operadores para que interprete javadoc (generalmente precedidos por @)

Un ejemplo de ello:

Yo recomiendo el texto ponerlo entre <p></p> ya que esto en html significa que es un párrafo. También utilizar todos los tags que podamos como si fuera un código html (que futuramente sera).

Al presionar F2  o posicionar el cursor (flecha del mouse) sobre el método, propiedad, etc. podemos ver el java doc.

Un ejemplo de ello:

Indicadores en Javadoc.

Como el Javadoc esta 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. 
Se usan indicadores para el número de versión (@version), el autor (@author) y otros. Es importante observar que los indicadores no son obligatorios; por ejemplo en un método sin parámetros no se incluye obviamente el indicador @param. También puede darse que un comentario incluya un indicador más de una vez, por ejemplo varios indicadores @param porque el método tiene varios parámetros.

Tipos de indicadores Javadoc

@author nombreDelAutor descripción.
Indica quién escribió el código al que se refiere el comentario. Si son varias personas se escriben los nombres separados por comas o se repite el indicador, según se prefiera. Es normal incluir este indicador en el comentario de la clase y no repetirlo para cada método, a no ser que algún método haya sido escrito por otra persona. 

@version númeroVersión descripción.
Si se quiere indicar la versión. Normalmente se usa para clases, pero en ocasiones también para métodos.
@param nombreParámetro descripción.
Para describir un parámetro de un método.
@return descripción.
Describe el valor de salida de un método.
@see nombre descripción. Cuando el trozo de código comentado se encuentra relacionada con otra clase o método, cuyo nombre se indica en nombre.
@throws nombreClaseExcepción descripción. Cuando un método puede lanzar una excepción ("romperse" si se da alguna circunstancia) se indica así.
@deprecated descripción. Indica que el método (es más raro encontrarlos para una clase) ya no se usa y se ha sustituido por otro. 

 @exception descripción. Es la excepción que se puede llegar a generar. Es un sinónimo para @exception.

 @since descripción.  Es la versión desde que se incluye.

¿Donde utilizar Javadoc?

El Javadoc se debe utilizar en:

• Clases.
• Métodos.
• Constructores.
• Constantes.
• Propiedades (Aunque no es muy común el uso en ellas).
• Paquetes.
• Etc.

Resumen

Habiendo dado argumentos que el Javadoc realmente es útil y necesario para documentar el código para nosotros y para los demás, no creen que todo proyecto debería poseer Javadoc?


Fuentes
Referencia 1
Referencia 2
Referencia 3