Documentación en Java: Uso de Etiquetas y Comentarios HTML

Clase 7 de 40 • Curso Avanzado de Java SE

Resumen

¿Cómo documentar un proyecto con JavaDocs?

Al comenzar un proyecto de software, es esencial contar con una documentación clara y precisa que permita a cualquier desarrollador comprender el alcance, las funcionalidades y las reglas de negocio del mismo. Una práctica recomendable es utilizar JavaDocs para generar esta documentación de manera estandarizada. Veamos cómo aplicar esta técnica a nuestro proyecto de manera efectiva.

¿Cómo estructurar la información de la clase principal?

La clase principal, que contiene el punto de entrada del proyecto, es el lugar ideal para comenzar a documentar tu aplicación. Aquí hay algunos pasos a seguir:

Usar el encabezado H1: Esto ayuda a definir el título del proyecto y su propósito general.

/**
 * <h1>Amazon Viewer</h1>
 * Amazon Viewer es un programa que permite visualizar movies, series, books y magazines.
 * Te permite generar reportes generales y con fecha del día.
 */

Proveer una descripción general: Detalla brevemente qué hace el programa, las características clave y las reglas generales que sigue.
Añadir etiquetas de autor y versión: Esto es crucial para el mantenimiento del proyecto.
```
* @author And
* @version 1.1
* @since 2018
*/
```

¿Cómo documentar clases abstractas?

La documentación de clases abstractas, como Film, sigue una estructura similar pero necesita enfatizar su carácter genérico:

Describir el carácter abstracto: Usa @code para resaltar métodos abstractos.

/**
 * <h1>Film</h1>
 * Film es una clase padre abstracta que representa la base de la familia de Film.
 * <p>Esta clase contiene el método abstracto {@code view} obligatorio de implementar.</p>
 * @author And
 * @version 1.1
 * @since 2018
 */

Mencionar métodos abstractos: Asegúrate de indicar claramente qué métodos deben ser implementados por las subclases.

¿Cómo añadir comentarios a interfaces y métodos?

La interfaz, como Visualizable, puede documentarse para indicar cómo debe ser utilizada:

Documentar métodos: Incluye información sobre los parámetros y los valores de retorno.

/**
 * Este método captura el tiempo exacto de visualización.
 * @param date Es un objeto de tipo {@code Date} con el tiempo exacto.
 * @return Devuelve la fecha y hora capturada.
 */

Describir parámetros y retornos: Usa @param y @return para especificar lo que recibe y devuelve un método.

Este enfoque de documentación no solo facilita la comprensión de cómo utilizar una clase o un método, sino que también mejora la mantenibilidad del código a largo plazo, permitiendo a diferentes desarrolladores trabajar en el mismo proyecto de manera eficiente. Por supuesto, es importante que cada sección de documentación sea clara y precisa para ser verdaderamente útil. No te olvides de que la práctica y consistencia te ayudarán a dominar la generación de documentación efectiva. ¡Sigue aprendiendo y mejorando tus habilidades!

Cesar David Ramírez Dimaté

student•

Resumen

/**
 * <h1>AmazonViewer</h1>
 * AmazonViewer es un programa que permite visualizar Movies, Series con sus respetivos Chapters, Books y Magazines.
 * <p>
 * Existen algunas reglas como todos los elementos pueden ser visualizados o leídos a excepción de las Magazines, estas sólo pueden ser vistas a modo de exposición sin ser leídas.
 * 
 * @author Cesar Ramírez
 * @version 1.1
 * @since 2018
 **/
public class Main { ... }

/**
 * <h1>Film</h1>
 * Film es una clase padre abstracta.
 * <p>
 * Es la clase base de la familia Films, como es abstracta no se puede instanciar y por ende contiene el método abstracto 
 * {@code view()} que es obligatorio implementar para todo aquél que pertenezca a la familia.
 * 
 * @author Cesar Ramírez
 * @version 1.1
 * @since 2018
 **/
public abstract class Film {
  ...
  /**
   * {@code view()} es un método abstracto obligatorio de implementar.
   **/
  public abstract void view();
}

public interface IVisualizable {
  /**
   * Este método captura el tiempo de inicio de visualización.
   * 
   * @param dateI Es un objeto {@code Date} con el tiempo de inicio exacto.
   * @return {@code Date} Devuelve la fecha y hora capturada.
   */
  Date startToSee(Date dateI);
  
  /**
   * Este método captura el tiempo exacto de inicio y final de visualización.
   * @param dateI Es un objeto {@code Date} con el tiempo de inicio exacto.
   * @param dateF Es un objeto {@code Date} con el tiempo final exacto.
   */
  void stopToSee(Date dateI, Date dateF);
}

Raul Castillo

student•

Buen aporte.

JUAN SEBASTIAN RODRIGUEZ JIMENEZ

student•

Gracias, buen aporte.

Luisa Fernanda Leguizamón Bayona

student•

Hola Todos. Para que automáticamente se coloquen los parámetros del método, se coloca /** y se da ENTER antes de la firma.

Arturo Munoz Cantor

student•

PERFECT... SO IS !!!

Noe de Jesus Muñoz Martinez

student•

Excelente clase de como documentar en Java.
Resumen:
En la clase Main:

/**
 * <h1>AmazonViewer</h1>
 * AmazonViewer es un programa que permite visualizar Movies, Series con sus respectivos Chapters, Books y Magazines.
 * Te permite generar reportes generales y con fecha del día.
 * <p>
 * Existen algunas reglas como todos los elementos pueden ser visualizados o leídos a excepción 
 * de las Magazines, estas sólo pueden ser vistas a modo de exposición sin ser leídas.
 * 
 * @author njmunoz
 * @version 1.1
 * @since 2019
 * */

En la clase Film

/**
 * <h1>Film</h1>
 * Film es una clase padre abstracta.
 * <p>
 * Es la clase base de la familia Films, como es abstracta no se puede instanciar y por ende contiene el método abstracto
 * {@code view()} que es obligatorio implementar para todo aquél que pertenezca a la familia.
 * 
 * @author njmunoz
 * @version 1.1
 * @since 2019
 * */

En el método abstract view de la clase Film:

/**
* {@code view()} es un método abstracto obligatorio de implementar.
 * */

En la clase IVisualizable:
Método startToSee:

/**
* Este método captura el tiempo exacto de inicio de visualización.
 * 
 * @param dateI Es un objeto {@code Date} con el tiempo de inicio exacto.
 * @return {@code Date} Devuelve la fecha y hora capturada.
 * */

Método stopToSee:

/**
* Este método captura el tiempo exacto de inicio y final de visualización.
* 
* @param dateI Es un objeto {@code Date} con el tiempo de inicio exacto.
* @param dateF Es un objeto {@code Date} con el tiempo final exacto.
* */

Francisco Prado

student•

Recomiendo leer el capitulo 4 de libro Codigo Limpio de Robert C. Martin, toda una catedra!!!
_
“No hay nada mas util que un comentario bien colocado. No hay nada que colapse más un modulo que comentarios dogmaticos innecesarios. No hay nada mas dañino que un comentario antiguo que propague mentiras y desinformacion…”_ Robert C. Martin

Daniel Meza

student•

Estaría genial un curso, aplicando convenciones de código limpio en nuestros proyectos.

Jose Luis Marin Escamilla

student•

Lo voy a leer.

José Gálvez

student•

Me encantó la explicación, soy de los que comentan todo y tener una forma de presentar esas explicaciones como documentación me parece genial.

NICOLAS ZAPATA ALZATE

student•

Se adelantó el vídeo en la parte de “Hereda” en la clase Movie en el minuto 11:11.

Cristian Ortega

student•

Es cierto, es como si hubieran cortado una parte de la clase.

Cesar David Ramírez Dimaté

student•

Lo hace es porque más adelante lo pone como un reto, de cómo hacer javadocs para herencias e interfaces.

Carlos Andres Carvajal

student•

En el minuto 11:11, iba a adicionar este comentario en la case Movie

/**
 * Hereda de {@link Film}
 * Implementea de {@link IVisualizable}
 * */

Carlos Andres Carvajal

student•

Iba a adicionar este comentario en la clase Movie, minuto 11:11

/**
 * Hereda de {@link Film}
 * Implementea de {@link IVisualizable}
 * */

Yossijaki Jorge Astilleros Chávez

student•

Excelente, solo me confundi un poco cuando vas a comentar el de Movie (hereda) pero ya vi que lo aclararas en la proxima clase.

Juan Carlos Barcinilla Alarcon

student•

Implemente mi propio código y clase.

/*
 * To change this license header, choose License Headers in Project Properties.
 * To change this template file, choose Tools | Templates
 * and open the template in the editor.
 */
package com.simple.pap.models;

import com.simple.pap.controllers.LeerPropiedad;
import java.sql.SQLException;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.sql.DataSource;
import java.sql.Connection;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import oracle.jdbc.pool.OracleDataSource;

/**
 * <h1>ConfigDb</h1>
 * <p>
 * Esta Clase abstracta extenderan todas las clases hija donde se quiera
 * realizar la conexcion a base datos. Ademas tienes un metodo
 * {@code systemIsWindows()} metodo que devuelve true si es sistemas y
 * {@code ruta()} metodo que devuelve la ruta donde esta desplegada la
 * aplicacion. windows.
 * </p>
 *
 * @author eforero
 * @version 1.0
 * @since 2018
 */
public abstract class ConfigDB {

    protected Connection conPosgress;
    protected Connection conMultiUsua;
    protected DataSource odsPosgrest;
    protected OracleDataSource ods;
    DataSource ds = null;

    /**
     * <h1>abrirConexionPG</h1>
     * <P>
     * Metodo que abre la conexion a base de datos de posgrest
     * </P>
     *
     * @author eforero
     * @version 1.0
     * @since 2018
     */
    public void abrirConexionPG() {

        try {
            Context ctx = new InitialContext();
            odsPosgrest = (DataSource) ctx.lookup(LeerPropiedad.leerPropiedades().getProperty("url.datasource.posgrest"));
            conPosgress = odsPosgrest.getConnection();
        } catch (SQLException | NamingException ex) {
            Logger.getLogger(ConfigDB.class.getName()).log(Level.SEVERE, null, ex);
        }
    }

    /**
     * <h1>cerrarConexionPG</h1>
     * <P>
     * Metodo que cierra la conexion a base de datos de posgrest
     * </P>
     *
     * @author eforero
     * @version 1.0
     * @since 2018
     * @author juan.barcinilla
     * @version 2.0
     * @since 2019-05-27
     */
    public void cerrarConexionPG() {
        try {
            if (!conPosgress.isClosed()) {
                conPosgress.close();
            }
        } catch (SQLException ex) {
            Logger.getLogger(ConfigDB.class.getName()).log(Level.SEVERE, null, ex);
        }
    }

    /**
     * <h1>conectarMultiusua</h1>
     * <P>
     * Metodo que abre la conexion a base de datos de Oracle
     * </P>
     *
     * @author eforero
     * @version 1.0
     * @since 2018
     * @author juan.barcinilla
     * @version 2.0
     * @since 2019-05-27
     */
    public void conectarMultiusua() {
        try {
            Context ctx = new InitialContext();
            ods = (OracleDataSource) ctx.lookup(LeerPropiedad.leerPropiedades().getProperty("url.datasource.oracle"));
            conMultiUsua = ods.getConnection();
        } catch (NamingException | SQLException ex) {
            Logger.getLogger(ConfigDB.class.getName()).log(Level.SEVERE, null, ex);
        }
    }

    /**
     * <h1>cerrarConexionMultisua</h1>
     * <P>
     * Metodo que cierra la conexion a base de datos de Oracle
     * </P>
     *
     * @author eforero
     * @version 1.0
     * @since 2018
     */
    public void cerrarConexionMultisua() {
        try {
            if (!conMultiUsua.isClosed()) {
                conMultiUsua.close();
            }
        } catch (SQLException ex) {
            Logger.getLogger(ConfigDB.class.getName()).log(Level.SEVERE, null, ex);
        }
    }

    /**
     * <h1>systemIsWindows()</h1>
     * <P>
     * Metodo que devuelve verdadero si el sistema operativo windows
     * </P>
     *
     * @author juan.barcinilla
     * @version 1.0
     * @since 2018
     * @return {@code boolean }
     */
    private boolean systemIsWindows() {
        return System.getProperty("os.name").startsWith("Windows");
    }

    /**
     * <h1>ruta()</h1>
     * <P>
     * Metodo que devuelve la ruta donde esta desplegada la aplicacion.
     * </P>
     *
     * @author juan.barcinilla
     * @version 1.0
     * @since 2018
     * @return {@code boolean }
     * @see {@code systemIsWindows()}
     */
    public String ruta() {
        String ruta;
        if (systemIsWindows()) {
            ruta = "C:\\Data\\archivo-pap";//PRUEBA LOCAL
        } else {
            ruta = "/media/archivo-pap";//PRODUCCION
        }
        return ruta;
    }

}

Misael Pereira Diaz

student•

En IDEs como IntelliJ y sus Derivados solo con poner /** y presionar enter les crea el JavaDocs

Andres Lopez

student•

creonque autor no es tan necesario en este scope, ya que git puede ayudar mucho más con blame.

KEVIN Cordon

student•

muy buena explicacion de como se impletementa java docs

Ronald Amiquero Zoiqui

student•

¿Porque la etiqueta de párrafo <p> no se cierra como la etiqueta <h1>? Muchas gracias por sus respuestas

Arturo Munoz Cantor

student•

En la sintaxis de HTML5, existen muchísimas etiquetas que no necesitan obligatoriamente etiqueta de cierre, aunque contengan a otros elementos dentro.

Muchas de ellas, además son de lo más común. Por ejemplo los párrafos, las listas, casi todos los elementos de las tablas, y por supuesto las propias etiquetas <html> y <body> que, de hecho, se pueden omitir por completo si queremos.

Norman Erick Estrada Vargas

student•

excelente explicación!!!

Eduardo Flores

student•

Pregunta, ¿Es necesario implementar el javadoc en absolutamente todos los métodos, incluso en los getters y setters?, Lo pregunto por que he visto algunos proyectos que lo hacen pero en lo personal creo que eso puede se exagerado.

Jair Israel Avilés Eusebio

student•

Depende, en realidad no es necesario documentar todos los metodos.

Misael Pereira Diaz

student•

Eso dependerá de los requerimientos del proyecto, a veces sobre el proyecto se deben de pasar informes de calidad del código (SonarQube) que puede requerir cierto porcentaje de código comentado.

Yossijaki Jorge Astilleros Chávez

student•

Cambia muy rapido de pestaña, un poco más de tiempo para ver como queda el comentario seria fenomenal. :P

Paul Cortes

student•

Muy buena clase sobre como usar los JavaDocs

Daniel Arturo Dominguez Lopez

student•

quedo muy claro como usar javadocs

Rafael Carrillo

student•

Muy interesante las etiquetas de documentación de java docs