JavaDoc

JavaDoc

javadoc es una utilidad java que genera páginas HTML de documentación del API a partir de ficheros con código fuente Java. Eso lo hace a partir de las especificaciones de las clases y de los comentarios que nosotros insertemos.

Los comentarios que se tomarán en cuenta para la documentación son los que tienen este formato:

/**
* Este es un comentario de documentación
*/

NO teniendo en cuenta cualquier otro formato de comentario

/*
* Este NO es un comentario de documentación
*/

/*  Este TAMPOCO es un comentario de documentación  */

Existen varias palabras claves para indicar ciertos campos comunes de la documentacion

@see nombre_de_clase

Añade un link a la clase en la zona “See Also”. Por ejemplo:

@see java.lang.String
@see String
@see String#equals
@see java.lang.Object#waint(int)
@see Character#MAX_RADIX
@see <A HREE="spec.html">Especif. Java</A>

El carácter # separa el nombre de una clase del nombre de uno de sus campos, métodos o constructores. Un comentario de documentación puede incluir más de una marca @see.

@version texto-version

Añade una entrada “Version”. El texto no tiene que tener formato especial. Un comentario de documentación puede incluir más de una marca @version.

@author texto-autor

Añade una entrada “Author”. El texto no tiene que tener formato especial. Un comentario de documentación puede incluir más de una marca @author.

@since texto

Este texto no tiene una estructura especial. Se utiliza para indicar desde qué fecha o desde qué versión se ha introducido el cambio o característica que indica el texto.

@deprecated texto

Añade un comentario indicando que no debería utilizarse la función o método, porque puede dejar de ser soportada por el API. La convención que se sigue es indicar en el texto la función o método por quien se ha sustituido. Por ejemplo:

@deprecated Replaced by setBounds(int,int,int,int)

Si el miembro está ya obsoleto y eliminado, el texto que sigue al tag @deprecated debe ser “No replacement”.

Ejemplo de comentario de una clase:

  /**
   * Clase que presenta una ventana en la pantalla.
   * Por ejemplo:
   * <PRE>
   *    Window ventana = new Window( padre );
   *    Ventana.show();
   * </PRE>
   *
   * @see        awt.BaseWindow
   * @see        awt.Button
   * @version    1.3 15 Ene 97
   * @author     Agustin Froufe
   */