JAVADOCJAVADOCHERRAMIENTA DE JAVA

RICARDO TIRIRA

PROGRAMACION II

COMENTARIOS EN JAVACOMENTARIOS EN JAVA

L

os comentarios son anotaciones en el código que el compilador

ignora pero son útiles para los programadores.

D

esde hace mucho tiempo se observó que en realidad los comentarios

se usaban para dos propósitos diferentes:

• Para explicar el propósito de sentencias o grupos de sentencias.

• Comentarios explicando qué hace una "pieza" cerrada de

código.

Para el primer tipo, comentarios "internos" se

usan los caracteres // seguidos del comentario,

o /* .... */ con el comentario en el lugar de los

puntos suspensivos.

int suma = 0; // al principio la suma int suma = 0; // al principio la suma vale 0 vale 0

System.out.println(suma); /* System.out.println(suma); /* finalmente mostramos el resultado finalmente mostramos el resultado por pantalla */por pantalla */

El segundo tipo, los usados para explicar qué

hace un código son los llamados en Java

comentarios JavaDoc, y se escriben

comenzando por /** y terminando con */ ,

pudiendo ocupar varias líneas. Mientras que

los comentarios usuales no tienen ningún

formato, los comentarios JavaDoc siguen una

estructura prefijada que describiremos mas

adelante.

FORMATO DE LOS COMENTARIOS FORMATO DE LOS COMENTARIOS

JAVADOCJAVADOC  

L

os comentarios JavaDoc están destinados a describir,

principalmente, clases y métodos.

C

omo están pensados para que otro programador los lea y utilice

la clase (o método) correspondiente,  se decidió que los

comentarios JavaDoc deben incluir unos indicadores especiales,

que comienzan siempre por '@' y se suelen colocar al comienzo

de línea.

@author  nombreDelAutor descripciónnombreDelAutor 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ónnúmeroVersión  descripcióndescripción..

Si se quiere indicar la versión. Normalmente se usa para clases, pero en ocasiones también para métodos.

@param  nombreParámetronombreParámetro  descripcióndescripción..

Para describir un parámetro de un método.    

@return  descripcióndescripción..

Informa de lo que devuelve el método, no se puede usar en constructores o métodos "void".

@see  nombrenombre  descripcióndescripción. .

Cuando el trozo de código comentado se encuentra relacionada con otra clase o método, cuyo nombre se indica en nombre. 

@deprecated  descripcióndescripción..

Indica que el método (es más raro encontrarlos para una clase) ya no se usa y se ha sustituido por otro. 

@throws  nombreClaseExcepciónnombreClaseExcepción  descripcióndescripción..

Cuando un método puede lanzar una excepción ("romperse" si se da alguna circunstancia) se indica así. 

 

COMENTARIOS DE DOCUMENTACIÓN

Un comentario de documentación se compone de los caracteres

 / ** que comienzan el comentario y terminan con los caracteres

 * /   se permiten en cada línea asteriscos lideres.

/ ** * comentarios * asterisco líder. * /

LA COLOCACIÓN DE LOS COMENTARIOS

s

ólo se reconocen cuando se coloca inmediatamente antes de las declaraciones de

la clase, interfaz, constructor, método, o en el campo . 

 

Sólo un comentario de documentación por instrucción de declaración se reconoce

por la herramienta Javadoc.

U

n error común es poner una importación como declaración entre el comentario de

clases y la declaración de la clase. 

/

** * Este es el comentario de clase para el Sea cual sea la clase. * / importación

com.sun; / / ERROR - Importante no poner la declaración de importación aquí

Cualquiera que sea la clase pública { }

Un error común es poner una importación como declaración entre el comentario de clases y la declaración de la clase. 

/ ** * Este es el comentario de clase. * / importación com.sun; / / ERROR - Importante no poner la declaración de importación aquí

public class nombre{ }

ERRORES

Un comentario de documentación se compone de una descripción principal seguida por una sección de la etiqueta.

/ ** * descripción principal. * @ See java.lang.Object */

Etiquetas de bloque : aparecen como @ etiqueta también conocido como “etiquetas independientes”.@etiqueta

Etiquetas en línea , se pueden utilizar tanto en la descripción principal como en la sección de etiquetas. Son de la forma: {@tag}

{@link package.class#member etiqueta} Crea un enlace con el texto "etiqueta" que apunta a la documentación del paquete, la clase o el miembro especificado.

TIPOS DE ETIQUETAS

LA HERRAMIENTA JAVADOC

l

a principal utilidad de estos comentarios es que pueden utilizarse

para generar la documentación de los programas.

E

l formato más sencillo de esta herramienta, cuando se emplea desde

línea de comandos es: javadoc nombre.javajavadoc nombre.java

L

o que hace esta herramienta es extraer los comentarios JavaDoc

contenidos en el programa Java indicado y construyendo con ellos

ficheros .html que puede servir como documentación de la clase.

HTMLHTML

H

TML, siglas de HyperText Markup Language («lenguaje de

marcado de hipertexto»), es el lenguaje de marcado

predominante para la elaboración de paginas web. Es usado para

describir la estructura y el contenido en forma de texto, así como

para complementar el texto con objetos tales como imágenes.

LENGUAJE DE MARCADO 

U

n lenguaje de marcado o lenguaje de marcas es una

forma de codificar un documento que, junto con el texto,

incorpora etiquetas o marcas que contienen información

adicional acerca de la estructura del texto o su

presentación.