Comentarios en Java (y II)

Comentarios en JAVA

Ya conocemos dos tipos de comentarios ¿Acaso hay mas?

Pues la respuesta es "true", en Java existe un tercer tipo de comentario llamados comentarios Javadoc.
Estos comentarios tienen la característica especial de que sirven para crear la documentación del programa con solo escribirlos. Esta documentación se crea con una utilidad llamada Javadoc del Kit de desarrollo de Java SE y se nos presenta en formato HTML.

¿y como los uso?

Un comentario Javadoc se escribirá igual que un comentario multilinea, con la diferencia de que no comenzará con /*, sino con /**.

Los comentarios Javadoc tienen 2 partes bien diferenciadas:

1. Descripción: Donde se aporta la descripción y datos importantes que facilitan la comprensión del elemento comentado.
2. Indicación: En la segunda parte del comentario se utiliza el indicador @ con ciertas palabras clave para que el programa, a la hora de realizar la documentación, sepa correctamente que estamos describiendo.

Normalmente se coloca un comentario Javadoc al inicio del programa en el que se describe que es lo que hará el mismo, la versión de la aplicación y el autor.

Este comentario quedaría así:

/**
 * Aquí iría una descripción sobre que va a hacer nuestro programa.
 * Podemos seguir la descripción en esta linea.
 * @version 1.0, 31/01/14
 * @author Sonando Java
 */

Las palabras reservadas para los indicadores son:


@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.