Java / Comentarios de documentacion

Bienvenidos sean a este post, hoy hablaremos sobre comentarios en la documentacion, y aunque si bien hemos hablado sobre como hacer comentarios en nuestro programas hoy nos centraremos en el otro tipo, veamos los tres tipos disponibles:

Comentario	Descripcion
/* texto */	El compilador ignora el texto entre los marcadores
// texto	El compilador ignora el texto hasta el final de la linea
/** documentacion */	Este es un comentario de documentacion y en general se llama doc comment.

En este ultimo caso el JDK javadoc usa este tipo de comentarios cuando prepara documentacion generada automaticamente para el codigo java, pero que es un javadoc?

Javadoc es una herramienta que viene con JDK y es utilizada para generar documentacion del codigo Java en formato HTML desde el codigo fuente de Java, el cual requiere documentacion en un formato predeterminado, veamos un simple ejemplo de este tipo de documentacion:

/**
* <h1> Mi Primer Programa </h1>
* Nuestro primer programa fue una aplicacion sencilla
* donde solamente mostrabamos el mitico mensaje de todo
* primer programa que es "Hello World".
* <p>
* Aca podemos ver que haciendo comentarios en tu programa
* lo transformas en algo mas amistoso para el usuario y le
* da una mejor calidad.
*
* @author tinchicus
* @version 1.0
* @since 2019-4-16
* </p>
*/

public class MiPrimerPrograma
{
        public static void main(String []args)
        {
                System.out.println("Hello World");
        }
}

Como pueden ver es nuestro primer programa donde mostrabamos el mensaje Hello World, observen como iniciamos con /**, despues por cada linea utilizamos el asterisco (*) y para finalizarlo usamos el */, tambien utilizamos un par de indicadores (@author, @version y @since) para indicar algunos datos especificos de nuestro programa pero esos los veremos un poco mas adelante, para compilar nuestro documento deberemos usar la siguiente sintaxis:

$javadoc nombrePrograma.java

Por ejemplo para compilar nuestro ejemplo deberiamos usar la siguiente linea:

$ javadoc MiPrimerPrograma.java

Si lo ejecutamos obtendremos la siguiente salida:

tinchicus@dbn001vrt:~/programacion/java/program$ javadoc MiPrimerPrograma.java
Loading source file MiPrimerPrograma.java…
Constructing Javadoc information…
Standard Doclet version 1.8.0_171
Building tree for all the packages and classes…
Generating ./MiPrimerPrograma.html…
Generating ./package-frame.html…
Generating ./package-summary.html…
Generating ./package-tree.html…
Generating ./constant-values.html…
Building index for all the packages and classes…
Generating ./overview-tree.html…
Generating ./index-all.html…
Generating ./deprecated-list.html…
Building index for all classes…
Generating ./allclasses-frame.html…
Generating ./allclasses-noframe.html…
Generating ./index.html…
Generating ./help-doc.html…
tinchicus@dbn001vrt:~/programacion/java/program$

Como se observa en la salida, estos son los distintos archivos que nos generara sobre nuestro codigo fuente los cuales contendran descripciones y otras ayudas sobre nuestro programa, a continuacion veamos una tabla de los modificadores utilizados por javadocs:

• @author, agrega el autor de la clase
• {@code}, muestra el codigo fuente sin interpretarlo como HTML o tags de javadoc
• {@docRoot}, representa el path realtivo al directorio raiz de los documentos generados
• @deprecated, agrega un comentario que esta API no debe ser usada
• @exception, agrega un subtítulo de lanzamientos a la documentación generada, con el nombre de la clase y el texto de la descripción.
• {@inheritDoc}, hereda un comentario de la clase heredable más cercana o la interfaz implementable.
• {@link}, inserta un enlace dentro de linea que apunta a la documentacion del paquete especificado
• {@linkplain}, idéntico a {@link}, excepto que la etiqueta del enlace se muestra en texto sin formato en lugar de la fuente del código.
• @param, agrega un parametro con el nombre de parametro especificado seguido de su descripcion
• @return, agrega una seccion de «regreso» con un texto
• @see, agrega una seccion «ver tambien» encabezado por un link o un texto que apunta a una referencia
• @serial, usado en el comentario para serializar un campo por defecto
• @serialData, documenta los datos escrito por writeExternal() o writeObject()
• @serialField, documenta un componente ObjectStreamField
• @since, agrega un encabezado «desde» con un texto para indicar cuando fue generado el documento
• @throws, hace exactamente lo mismo a @exception
• {@value}, cuando se usa un campo estatico para este parametro, se muestra ese valor constante
• @version, agrega un encabezado de version con el valor informado

En general estos parametros si no llevan las llaves ({}) solo reciben un parametro, en cambio si tienen las llaves son para indicar mas de un valor: p.e. {@code texto de prueba }.

En resumen, esta es la forma para documentar nuestros programas por medio de su codigo fuente y la utilidad javadoc, hemos visto los parametros que se pueden usar para asignar uno u otra informacion, hemos visto un ejemplo de como se aplica y hemos visto como se compila, espero les haya sido util sigueme en tumblr, Twitter o Facebook para recibir una notificacion cada vez que subo un nuevo post en este blog, nos vemos en el proximo post.

Tengo un Patreon donde podes acceder de manera exclusiva a material para este blog antes de ser publicado, sigue los pasos del link para saber como.