Java - Comentarios de documentación
El lenguaje Java admite tres tipos de comentarios:
| No Señor. | Comentario y descripción |
|---|---|
| 1 | /* text */ El compilador ignora todo, desde / * hasta * /. |
| 2 | //text El compilador ignora todo desde // hasta el final de la línea. |
| 3 | /** documentation */ Este es un comentario de documentación y en general se llama doc comment. losJDK javadocLa herramienta utiliza comentarios de documentos al preparar documentación generada automáticamente. |
Este capítulo trata de explicar Javadoc. Veremos cómo podemos hacer uso de Javadoc para generar documentación útil para código Java.
¿Qué es Javadoc?
Javadoc es una herramienta que viene con JDK y se utiliza para generar documentación de código Java en formato HTML a partir del código fuente de Java, que requiere documentación en un formato predefinido.
A continuación se muestra un ejemplo sencillo en el que las líneas dentro de /*….*/ son comentarios de varias líneas de Java. De manera similar, la línea que precede // es un comentario de una sola línea de Java.
Ejemplo
/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}Puede incluir las etiquetas HTML necesarias dentro de la parte de descripción. Por ejemplo, el siguiente ejemplo utiliza <h1> .... </h1> para el encabezado y <p> se ha utilizado para crear un salto de párrafo
Ejemplo
/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}Las etiquetas javadoc
La herramienta javadoc reconoce las siguientes etiquetas:
| Etiqueta | Descripción | Sintaxis |
|---|---|---|
| @autor | Agrega el autor de una clase. | @autor nombre-texto |
| {@código} | Muestra texto en fuente de código sin interpretar el texto como marcado HTML o etiquetas javadoc anidadas. | {@code text} |
| {@docRoot} | Representa la ruta relativa al directorio raíz del documento generado desde cualquier página generada. | {@docRoot} |
| @obsoleto | Agrega un comentario que indica que esta API ya no debe usarse. | @deprecated deprecatedtext |
| @excepción | Agrega un Throws subtítulo de la documentación generada, con el nombre de la clase y el texto de descripción. | @exception descripción del nombre de clase |
| {@inheritDoc} | Hereda un comentario del nearest clase heredable o interfaz implementable. | Hereda un comentario de la superclase inmediata. |
| {@enlace} | Inserta un enlace en línea con la etiqueta de texto visible que apunta a la documentación del paquete, la clase o el nombre de miembro especificado de una clase referenciada. | {@link package.class # member label} |
| {@linkplain} | Idéntico a {@link}, excepto que la etiqueta del vínculo se muestra en texto sin formato que en fuente de código. | {@linkplain package.class # member label} |
| @param | Agrega un parámetro con el nombre de parámetro especificado seguido de la descripción especificada a la sección "Parámetros". | @param descripción del nombre del parámetro |
| @regreso | Agrega una sección "Devoluciones" con el texto de descripción. | @return descripción |
| @ver | Agrega un encabezado "Ver también" con un vínculo o entrada de texto que apunta a una referencia. | @ver referencia |
| @de serie | Se usa en el comentario del documento para un campo serializable predeterminado. | @serial campo-descripción | incluir | excluir |
| @serialData | Documenta los datos escritos por los métodos writeObject () o writeExternal (). | @serialData descripción de datos |
| @serialField | Documenta un componente ObjectStreamField. | @serialField nombre de campo tipo de campo descripción de campo |
| @ya que | Agrega un encabezado "Desde" con el texto desde especificado a la documentación generada. | @desde lanzamiento |
| @tiros | Las etiquetas @throws y @exception son sinónimos. | @throws descripción del nombre de clase |
| {@valor} | Cuando se usa {@value} en el comentario de documento de un campo estático, muestra el valor de esa constante. | {@value package.class # field} |
| @versión | Agrega un subtítulo "Versión" con el texto de la versión especificado a los documentos generados cuando se usa la opción -version. | @version versión-texto |
Ejemplo
El siguiente programa utiliza algunas de las etiquetas importantes disponibles para comentarios de documentación. Puede utilizar otras etiquetas según sus requisitos.
La documentación sobre la clase AddNum se producirá en el archivo HTML AddNum.html pero al mismo tiempo también se creará un archivo maestro con el nombre index.html.
import java.io.*;
/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class AddNum {
/**
* This method is used to add two integers. This is
* a the simplest form of a class method, just to
* show the usage of various javadoc Tags.
* @param numA This is the first paramter to addNum method
* @param numB This is the second parameter to addNum method
* @return int This returns sum of numA and numB.
*/
public int addNum(int numA, int numB) {
return numA + numB;
}
/**
* This is the main method which makes use of addNum method.
* @param args Unused.
* @return Nothing.
* @exception IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException {
AddNum obj = new AddNum();
int sum = obj.addNum(10, 20);
System.out.println("Sum of 10 and 20 is :" + sum);
}
}Ahora, procese el archivo AddNum.java anterior utilizando la utilidad javadoc de la siguiente manera:
$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
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...
1 warning
$Puedes consultar toda la documentación generada aquí - AddNum . Si está utilizando JDK 1.7, javadoc no genera una granstylesheet.css, por lo que sugerimos descargar y utilizar la hoja de estilo estándar de https://docs.oracle.com/javase/7/docs/api/stylesheet.css