3. COMENTARIOS EN JAVACOMENTARIOS EN JAVA
os comentarios son anotaciones en el código que el compilador
ignora pero son útiles para los programadores.
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.
4. 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 vale 0int suma = 0; // al principio la suma vale 0
System.out.println(suma); /* finalmente mostramos elSystem.out.println(suma); /* finalmente mostramos el
resultado por pantalla */resultado por pantalla */
5. 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.
6. FORMATO DE LOS COMENTARIOS JAVADOCFORMATO DE LOS COMENTARIOS JAVADOC
os comentarios JavaDoc están destinados a describir, principalmente,
clases y métodos.
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.
7. @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.
8. @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.
9. @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í.
10. 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.
* /
11. LA COLOCACIÓN DE LOS
COMENTARIOS
ó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.
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 { }
12. 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
13. 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
*/
14. 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
15.
16. LA HERRAMIENTA JAVADOC
a principal utilidad de estos comentarios es que pueden utilizarse para
generar la documentación de los programas.
l formato más sencillo de esta herramienta, cuando se emplea desde
línea de comandos es: javadoc nombre.javajavadoc nombre.java
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.
17.
18.
19. HTMLHTML
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.
20. LENGUAJE DE MARCADO
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.
