Java - Documentación Comentarios
El lenguaje Java admite tres tipos de comentarios −
| Sr.No. | Comentario y descripción |
|---|---|
| 1 | /* texto */ El compilador ignora todo, desde /* hasta */. |
| 2 | //texto El compilador ignora todo desde // hasta el final de la línea. |
| 3 | /** documentación */ Este es un comentario de documentación y en general se llama comentario de doc . El documento javadoc de JDK la herramienta utiliza comentarios de documentos al preparar la documentación generada automáticamente. |
Este capítulo se trata de explicar Javadoc. Veremos cómo podemos hacer uso de Javadoc para generar documentación útil para el 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, lo que requiere documentación en un formato predefinido.
El siguiente es un ejemplo simple donde las líneas dentro de /*….*/ son comentarios de varias líneas de Java. Del mismo modo, la línea que precede a // 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 etiquetas HTML requeridas dentro de la parte de descripción. Por ejemplo, el siguiente ejemplo utiliza
....
para el encabezado yse 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. | {@texto de código} |
| {@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 tiro subtítulo de la documentación generada, con el nombre de clase y el texto de descripción. | @exception class-name description |
| {@inheritDoc} | Hereda un comentario del más cercano 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, clase o nombre de miembro especificado de una clase a la que se hace referencia. | {@link package.class#member label} |
| {@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. | {@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 |
| @return | Agrega una sección de "Devoluciones" con el texto de descripción. | @return descripción |
| @ver | Agrega un encabezado "Ver también" con un enlace o entrada de texto que apunta a la referencia. | @ver referencia |
| @serial | Usado en el comentario del documento para un campo serializable predeterminado. | @serial field-description | 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-campo tipo-campo descripción-campo |
| @since | Agrega un encabezado "Desde" con el texto desde especificado a la documentación generada. | @desde el lanzamiento |
| @lanzamientos | Las etiquetas @throws y @exception son sinónimos. | @throws descripción del nombre de la clase |
| {@valor} | Cuando se usa {@value} en el comentario del 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 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 los comentarios de la 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 usando 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 un gran stylesheet.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
Java