javadoc
Post on 26-Jul-2015
40 Views
Preview:
TRANSCRIPT
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.
top related