fbpx
Seleccionar página

Crear documentación de java para nuestros proyectos es de vital importancia, ya que lo que hagamos tenemos que documentarlo.

Esto va a servir a otros programadores a entender de una forma fácil todo lo que se hizo en un proyecto y saber para qué sirve cada clase, interface y cada método.

Como vimos en el capítulo pasado del manejo de la documentación de Java, esta es muy importante para saber para qué sirven las clases y sus métodos.

La documentación que realizaremos será muy parecida a la documentación oficial javaDoc y será accedida de igual forma desde un navegador web.

Para crear documentación javaDoc de nuestro proyecto, los editores de Java como son: Eclipse, NetBeans, JDeveloper, etc, cuentan con opciones de menú que ejecutan la herramienta de creación de documentación de nuestros proyectos.

Crear documentación de Java – javaDoc

En mi caso como estoy usando NetBeans para los ejemplos, usare dicha herramienta para generar un ejemplo de javaDoc:

Para generar la documentación de java se puede hacer de dos formas:

  1. Desde nuestro Editor preferido.
  2. Desde línea de comandos.

[wpsm_ads1]

Independientemente de la opción que escojamos, se usara la herramienta “javadoc” de nuestro JDK.
La documentación se va a generar en formato HTML de forma local dentro de nuestro proyecto.

Para poder generar la documentación de alguna clase o método se tienen que usar etiquetas HTML precedidas del carácter “@”. Las etiquetas tienen que estar dentro de un comentario java iniciando con “/**” y terminando con “*/”.

Estos comentarios con etiquetas de documentación pueden ir al inicio de:

  1. Una clase.
  2. Un atributo.
  3. Un método.

Etiquetas javaDoc

A continuación, veremos una lista de las etiquetas más comunes para generar JavaDoc:

Etiqueta Descripción
@author Indica el nombre de quien desarrollo el componente.
@deprecated Indica que algún método o clase u otro componente está obsoleto.
@param Indica un parámetro de un método, se tiene que usar para todos los parámetros del método.
@return Indica el valor de retorno de un método
@see Indica que el componente puede hacer referencia a otro. Ejemplo: #método(); clase#método();
@throw Indica que excepción lanza el método.
@version Indica la versión actual del componente.

[wpsm_ads2]

Ya que sabemos algunas de las etiquetas más importantes para crear documentación en Java, el paso siguiente es agregar los comentarios con dichas etiquetas en nuestras clases, interfaces y métodos.

Ejemplo de javaDoc

Como ejemplo vamos a usar la clase Empleado que creamos para los ejemplos pasados de Herencia.

package cursojava;

/**
 * Esta clase contiene los atributos y metodos de un empleado
 * @author Mario Celis
 * @version 1.0
 * @see Persona
 */
public class Empleado extends Persona{
    
    private int numeroEmpleado;
    private String departamento;
    private String puesto;
    
    /**
     * Metodo constructor por defecto
     */
    public Empleado(){
    }
    
    /**
     * Metodo constructor parametrizado
     * @param nombre Nombre del empleado
     * @param edad Edad del empleado
     * @param sexo Sexo del empleado en formato H o M
     * @param numeroEmpleado Numero de empleado
     * @param departamento Departamento donde trabajara el empleado
     * @param puesto Puesto que ocupara el empleado dentro de la empresa
     */
    public Empleado(String nombre, 
                    int edad, 
                    char sexo, 
                    int numeroEmpleado, 
                    String departamento, 
                    String puesto){
        super(nombre, edad, sexo);
        this.numeroEmpleado = numeroEmpleado;
        this.departamento = departamento;
        this.puesto = puesto;
    }
    
    /**
     * Metodo para regresar el numero de empelado
     * @return Regresa el numero del empleado
     */
    public int getNumeroEmpleado() {
        return numeroEmpleado;
    }
    
    /**
     * Establece el numero del empleado
     * @param numeroEmpleado Numero que se le asignara al empleado
     */
    public void setNumeroEmpleado(int numeroEmpleado) {
        this.numeroEmpleado = numeroEmpleado;
    }
    
    /**
     * Metodo que regresa el nombre del departamento asignado al empleado
     * @return Regresa el departamento
     */
    public String getDepartamento() {
        return departamento;
    }
    
    /**
     * Metodo que le asigna departamento a un empelado
     * @param departamento Nombre de departamento
     */
    public void setDepartamento(String departamento) {
        this.departamento = departamento;
    }
    
    /**
     * Metodo que regresa el puesto del empleado
     * @return Regresa un String que indica el puesto
     */
    public String getPuesto() {
        return puesto;
    }
    
    /**
     * Metodo que establece el puesto del empleado
     * @param puesto Indica el puesto del empleado
     */
    public void setPuesto(String puesto) {
        this.puesto = puesto;
    }
}

Una vez que ya tengamos todas nuestras Clases, interfaces, etc documentadas, procedemos a crear documentación de Java. En NetBeans se hace de la siguiente manera.

Generar javaDoc en NetBeans

Clic derecho sobre nuestro proyecto y seleccionamos la opción “Generate Javadoc”.

Crear Documentación de Java desde NetBeans

El editor comienza a generar la documentación de nuestro proyecto.

Log de la creación de documentación de Java

Abrimos la ruta y entramos a la carpeta javadoc, vemos que se crearon varios archivos, buscamos el archivo “index.html” y lo abrimos con un navegador web.

Archivos generados por javadoc

Listo, ya tenemos la documentación Java de nuestro proyecto, el comando “javadoc” detectó todos los objetos que creamos en nuestro proyecto.

[wpsm_ads1]

Creo sus páginas de documentación, realizo el orden por paquetes, listado de clases y contenidos.

Ejemplo de una pagina de javaDoc

Ya podemos comenzar a revisar nuestra documentación.

JavaDoc de métodos constructores

Al dar clic en el link del método nos manda directo a su especificación.

Descripción javadoc de un método

Bien, espero que con esta información ya sepas como crear documentación de Java de tus proyectos Java.

Este sitio web utiliza cookies para que usted tenga la mejor experiencia de usuario. Si continúa navegando está dando su consentimiento para la aceptación de las mencionadas cookies y la aceptación de nuestra política de cookies, pinche el enlace para mayor información.

ACEPTAR
Aviso de cookies