Java: Javadoc: Documentación

Se aconseja, como buena práctica de programación, incluir en la entrega de la aplicación la documentación de los ficheros fuente de todas las clases. Dicha documentación será generada por la herramienta "javadoc".

La herramienta "javadoc" construirá la documentación a partir de los comentarios (incluidos en las clases) encerrados entre los caracteres "/**" y "*/". Distinguimos tres tipos de comentarios javadoc, en función del elemento al que preceden: de clase, de variable y de método.

Dentro de los comentarios "javadoc" podremos incluir código html y etiquetas especiales de documentación. Estas etiquetas de documentación comienzan con el símbolo "@", se sitúan al inicio de línea del comentario y nos permiten incluir información específica de nuestra aplicación de una forma estándar.

Como norma general utilizaremos las siguientes etiquetas:

@author Nombre

Añade información sobre el autor o autores del código.

@version InformacionVersion

Permite incluir información sobre la versión y fecha del código.

@param NombreParametro Descripción

Inserta el parámetro especificado y su descripción en la sección "Parameters:" de la documentación del método en el que se incluya. Estas etiquetas deben aparecer en el mismo orden en el que aparezcan los parámetros especificados del método. Este tag no puede utilizarse en comentarios de clase, interfaz o campo. Las descripciones deben ser breves.

@return Descripción

Inserta la descripción indicada en la sección "Returns:" de la documentación del método. Este tag debe aparecer en los comentarios de documentación de todos los métodos, salvo en los constructores y en aquellos que no devuelvan ningún valor (void).

@throws NombreClase Descripción

Añade el bloque de comentario "Throws:" incluyendo el nombre y la descripción de la excepción especificada. Todo comentario de documentación de un método debe contener un tag "@throws" por cada una de las excepciones que pueda elevar. La descripción de la excepción puede ser tan corta o larga como sea necesario y debe explicar el motivo o motivos que la originan.

@see Referencia

Permite incluir en la documentación la sección de comentario "See also:", conteniendo la referencia indicada. Puede aparecer en cualquier tipo de comentario "javadoc". Nos permite hacer referencias a la documentación de otras clases o métodos.

@deprecated Explicación

Esta etiqueta indica que la clase, interfaz, método o campo está obsoleto y que no debe utilizarse, y que dicho elemento posiblemente desaparecerá en futuras versiones. "javadoc" añade el comentario "Deprecated" en la documentación e incluye el texto explicativo indicado tras la etiqueta. Dicho texto debería incluir una sugerencia o referencia sobre la clase o método sustituto del elemento "deprecado".

@since Version

Se utiliza para especificar cuando se ha añadido a la API la clase, interfaz, método o campo. Debería incluirse el número de versión u otro tipo de información.

El siguiente ejemplo muestra los tres tipos de comentarios "javadoc",


/**
 * UnidadOrganizativa.java:
 * 
 *  Clase que muestra ejemplos de comentarios de documentación de código. 
 * 
 * @author jlflorido
 * @version 1.0, 05/08/2008
 * @see documento "Normas de programación v1.0"
 * @since jdk 5.0 
 */
public class UnidadOrganizativa extends PoolDAO {

    /** Trazas de la aplicación */
    private Logger log = Logger.getLogger(UnidadOrganizativa.class);

    /** Identificador de la unidad organizativa */
    private int id;
 
    /** Nombre de la unidad organizativa */
    private String nombre;

    /** Obtiene el identificador de esta unidad organizativa */
    public int getId() {
        return id;
    }

    /** Establece el identificador de esta unidad organizativa */
    public void setId(int id) {
        this.id = id;
    }
 
    /** Obtiene el nombre de esta unidad organizativa */
    public String getNombre() {
        return nombre;
    }

    /** Establece el nombre de esta unidad organizativa */
    public void setNombre(String nombre) {
        this.nombre = nombre;
    }
 
    /**
     * Inserta la unidad organizativa en el sistema.
     * 
     * @param unidad Unidad organizativa a insertar
     * @throws Exception Excepción elevada durante el proceso de inserción
     */
    public void insertarUnidad(UnidadOrganizativa unidad) throws Exception{
  
        log.debug("-> insertarUnidad(UnidadOrganizativa unidad)");
  
        Connection conn = null;
        PreparedStatement pstmt = null;
        StringBuffer sqlSb = null;
  
        try {
            conn = this.dameConexion();
      
            sqlSb = new StringBuffer("")
            .append("INSERT INTO ORG.UNIDAD_ORGANIZATIVA ")
            .append("(ID, NOMBRE) VALUES (?, ?)");
      
            pstmt = conn.prepareStatement(sqlSb.toString());
            pstmt.setInt(1, unidad.getId());
            pstmt.setString(2, unidad.getNombre());
            pstmt.executeUpdate();
   
        } catch (Exception e) {

            log.error("Error: error al insertar la unidad. " +
            "Descripción:" + e.getMessage(), e);

            throw e;

        } finally {

            log.debug("<- insertarUnidad(UnidadOrganizativa unidad)");

        }
    }
}

La documentación generada por "javadoc" será la siguiente:

a) Página índice de toda la documentación generada: