Comentarios de documentación de Java

Java admite tres tipos de comentarios:

  • Comentario de una sola línea
  • Comentario de varias líneas
  • Comentario de documentación

Los dos primeros tipos son, respectivamente,//y/* */el tercero se denomina comentario de documentación, que usa/**para comenzar, y*/para terminar.

El contenido de los dos primeros tipos de comentarios se puede consultar en:Comentarios de Java

Los comentarios de documentación te permiten incrustar información sobre el programa dentro del programa.

Puedes usar la herramienta de software javadoc para generar la información y enviarla a un archivo HTML.

Los comentarios de documentación te permiten registrar la información de tu programa de forma más conveniente.

Etiquetas de javadoc

La herramienta javadoc reconoce las siguientes etiquetas:

Etiqueta Descripción Ejemplo
@author Identifica al autor de una clase. @author description
@deprecated Indica una clase o miembro obsoleto. @deprecated description
{@docRoot} Indica la ruta del directorio raíz del documento actual. Directory Path
@exception Señala una excepción lanzada por una clase. @exception exception-name explanation
{@inheritDoc} Un comentario heredado de la clase padre directa. Inherits a comment from the immediate surperclass.
{@link} Inserta un enlace a otro tema. {@link name text}
{@linkplain} Inserta un enlace a otro tema, pero el enlace se muestra en texto sin formato. Inserts an in-line link to another topic.
@param Documenta un parámetro de un método. @param parameter-name explanation
@return Documenta el tipo de valor de retorno. @return explanation
@see Especifica un enlace a otro tema. @see anchor
@serial Documenta una propiedad de serialización. @serial description
@serialData Documenta los datos escritos mediante los métodos writeObject( ) y writeExternal( ). @serialData description
@serialField Documenta un componente ObjectStreamField. @serialField name type description
@since Marca cuándo se introduce un cambio específico. @since release
@throws Igual que la etiqueta @exception. The @throws tag has the same meaning as the @exception tag.
{@value} Muestra el valor de una constante; dicha constante debe ser un atributo static. Displays the value of a constant, which must be a static field.
@version Especifica la versión de una clase. @version info

Comentarios de documentación

Después del/**la primera línea o las primeras líneas son la descripción principal sobre la clase, las variables y los métodos.

Después, puedes incluir una o más de las diversas@etiquetas. Cada@etiqueta debe estar al comienzo de una nueva línea o, al inicio de una línea, inmediatamente después del asterisco.*。

Varias etiquetas del mismo tipo deben agruparse. Por ejemplo, si tienes tres@seeetiquetas, puedes colocarlas una tras otra juntas.

A continuación se muestra un ejemplo de un comentario de una clase:

/*** Esta clase dibuja un gráfico de barras * @author ejemplo * @version 1.2 */

Qué genera javadoc

La herramienta javadoc toma como entrada el código fuente de tu programa Java y genera archivos HTML que contienen los comentarios de tu programa.

La información de cada clase se guardará en su propio archivo HTML. javadoc también puede generar el árbol de herencia y un índice.

Como las implementaciones de javadoc pueden diferir, el funcionamiento también puede variar. Debes comprobar detalles como la versión de tu sistema de desarrollo Java y elegir la versión de Javadoc adecuada.

Ejemplo

A continuación se muestra un ejemplo sencillo que utiliza comentarios de documentación. Observa que cada comentario está delante del elemento que describe.

Tras el procesamiento con javadoc, el comentario de la clase SquareNum se encontrará en SquareNum.html.

Código del archivo SquareNum.java:

import java.io.*; /** * Esta clase demuestra los comentarios de documentación * @author Ayan Amhed * @version 1.2 */ public class SquareNum { /** * This method returns the square of num. * This is a multiline description. You can use * as many lines as you like. * @param num The value to be squared. * @return num squared. */ public double square(double num) { return num * num; } /** * This method inputs a number from the user. * @return The value input as a double. * @exception IOException On input error. * @see IOException */ public double getNumber() throws IOException { InputStreamReader isr = new InputStreamReader(System.in); BufferedReader inData = new BufferedReader(isr); String str; str = inData.readLine(); return (new Double(str)).doubleValue(); } /** * This method demonstrates square(). * @param args Unused. * @return Nothing. * @exception IOException On input error. * @see IOException */ public static void main(String args[]) throws IOException { SquareNum ob = new SquareNum(); double val; System.out.println("Enter value to be squared: "); val = ob.getNumber(); val = ob.square(val); System.out.println("Squared value is " + val); } }

A continuación, utiliza la herramienta javadoc para procesar el archivo SquareNum.java:

$ javadoc SquareNum.java
Loading source file SquareNum.java...
Constructing Javadoc information...
Standard Doclet version 1.5.0_13
Building tree for all the packages and classes...
Generating SquareNum.html...
SquareNum.java:39: 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...
Generating stylesheet.css...
1 warning
$
Otras extensiones