Documentación de Clases Heredadas en Java

Clase 9 de 40 • Curso Avanzado de Java SE

Resumen

¿Cómo manejar la herencia y los enlaces en la generación de documentación con JavaDoc?

La documentación detallada es fundamental para cualquier proyecto de software. Nos permite no solo entender mejor el funcionamiento del código, sino también facilitar futuras expansiones y colaboraciones. Aquí te mostraremos cómo manejar JavaDoc para clases que heredan otras y cómo crear enlaces útiles dentro de la documentación.

¿Qué es JavaDoc y cómo lo hemos estado usando?

JavaDoc es una herramienta poderosa para generar documentación API a partir de comentarios en el código fuente. Permite describir la funcionalidad de clases, métodos y campos de forma clara y accesible. En nuestras clases previas ya vimos cómo documentar parámetros y retornos, y ahora profundizaremos en la documentación de herencia y enlaces.

¿Cómo documentar clases heredadas?

Cuando trabajamos con clases que heredan de otras, es crucial incluir esta relación en la documentación. JavaDoc nos permite hacerlo de manera sencilla:

Herencia: Utiliza los brackets para enlazar a las clases de las que se hereda o que se implementan, creando enlaces directos:
```
/**
 * {@link Film}
 * {@link VisualDisabled}
 */
public class Movie extends Film implements VisualDisabled {
    ...
}
```
Al utilizar @link, no solo mencionamos las otras clases, sino que también generamos un enlace clicable que llevará a la documentación de la clase especificada.

¿Cómo utilizar InheritDoc para métodos?

A menudo, cuando sobrescribes métodos de una clase padre, la documentación puede volverse redundante. JavaDoc ofrece la etiqueta @inheritDoc que permite heredar la documentación de la superclase:

Ejemplo de InheritDoc:
```
/**
 * {@inheritDoc}
 */
@Override
public void view() {
    ...
}
```
Esta etiqueta automáticamente extrae la documentación de la clase padre al nuevo método, evitando duplicidades y manteniendo la consistencia.

¿Cómo visualizar la documentación generada?

Gracias a las etiquetas que hemos usado y al formato que JavaDoc proporciona, la documentación se vuelve navegable e intuitiva:

Visualización de una clase: Al comenzar a escribir el nombre de una clase en tu IDE, debería mostrarse un resumen de la documentación disponible.
Exploración de métodos y enlaces: Al clicar en los enlaces generados con @link, puedes navegar fácilmente entre las distintas clases y sus respectivas documentaciones.

¿Qué reto puedes asumir ahora?

Ahora que entiendes cómo trabajar con herencia y enlaces en JavaDoc, te desafío a integrar otras dos etiquetas de las que hemos discutido anteriormente. Incorpóralas a tu proyecto y observa cómo añaden valor a tu documentación. Comparte tus resultados; el aprendizaje colaborativo es inestimable y seguro aprenderás al compartir tus experiencias.

Este es solo el comienzo. La documentación bien estructurada no solo hará que tu proyecto sea más sólido, sino que también facilitará compartir tu trabajo y colaborar con otros ingenieros. ¡Continúa expandiendo tus habilidades en Java y JavaDoc!

Jair Israel Avilés Eusebio

student•

Para generar el JavaDoc desde IntelliJ IDEA se debe de dar click en el menu y opción Tools | Generate JavaDoc...

Victor Hugo Vázquez Gómez

student•

¡Muchas gracias!

César Espitia

student•

Excelente aporte, gracias!!!

Jaime Alexander Uribe Uribe

student•

Documentando la clase AmazonUtil

Ya documentado

Santiago Asmal

student•

Muy bien!!

Jhoni Omar Torres Mata

student•

gracias

Noe de Jesus Muñoz Martinez

student•

Excelente clase.

Sroba

student•

Sobre la clase padre Publication:

/** 
 * <h1>Publication</h1>
 * Es una clase padre 
 * <p>
 * Esta es una clase base de la familia Publication, la cual  
 * contiene atributos para Book y Magazine
 * 
 * @author Sroba 
 * @version 1.1
 * @since 2018
 * 
 * */

Luego sobre el método isRead

/**
     * {@code isRead()} es un método que nos devuelve la 
     *  respuesta de si se vió o no el libro o el Magazine
     * */

Yossijaki Jorge Astilleros Chávez

student•

package com.yossi.amazonviewer.model;

/**
 * <h1>Magazine</h1>
 * Este contenido es solo para visualización sin posibilidad de abrir el contenido
 * 
 * 
 * 
 * @author yastilleros
 * @version 1.1
 * */

import java.util.ArrayList;
import java.util.Date;

public class Magazine extends Publication {
...
}

Eduardo Flores

student•

En la clase serie

/**
 * Hereda de {@link Film}
 * Esta clase representa una serie
 * @author eduardo
 * @since 2018
 * @version 1.0.0
 */
...

Gerald Zamora

student•

package com.anncode.amazonviewer.model;

import java.util.ArrayList;

/**
 *  <h1> Serie </h1>
 * <p>Serie una clase que hereda {@link Film}</p>
 *
 * @author gerald
 * @version 1.1
 * @since 2019
 */
public class Serie extends Film {
	
	private int id;
	private int sessionQuantity;
	private ArrayList<Chapter> chapters;
	

	public Serie(String title, String genre, String creator, int duration, int sessionQuantity) {
		super(title, genre, creator, duration);
		this.sessionQuantity = sessionQuantity;
	}
	
	

	public int getId() {
		return id;
	}

	public int getSessionQuantity() {
		return sessionQuantity;
	}

	public void setSessionQuantity(int sessionQuantity) {
		this.sessionQuantity = sessionQuantity;
	}

	public ArrayList<Chapter> getChapters() {
		return chapters;
	}

	public void setChapters(ArrayList<Chapter> chapters) {
		this.chapters = chapters;
	}
	
	@Override
	public String toString() {
		return  "\n :: SERIE ::" + 
				"\n Title: " + getTitle() +
				"\n Genero: " + getGenre() + 
				"\n Year: " + getYear() + 
				"\n Creator: " + getCreator() +
				"\n Duration: " + getDuration();
	}

	public static ArrayList<Serie> makeSeriesList() {
		ArrayList<Serie> series = new ArrayList<Serie>();
		
		for (int i = 1; i <= 5; i++) {
			Serie serie = new Serie("Serie "+i, "genero "+i, "creador "+i, 1200, 5);
			serie.setChapters(Chapter.makeChaptersList(serie));
			series.add(serie);
			
		}
		
		return series;
	}
	
}

Moisés Abraham Croes Gómez

student•

Mi respuesta al reto de esta clase, utilizando las tags @link y @inheritDoc:

Magazine

package com.moisescode.amazonviewer.model;

import java.util.ArrayList;
import java.util.Date;

/**
 *<h1>Magazine</h1>
 * Esta clase hereda de {@link Publication}
 * 
 * @author Moises
 *
 */
public class Magazine extends Publication {

	private int id;


	public Magazine(String title, Date editionDate, String editorial) {
		super(title, editionDate, editorial);
	}

	
	public int getId() {
		return id;
	}

	/**
	 * {@inheritDoc}
	 */
	@Override
	public String toString() {
		String detailMagazine =
				"\n Title: " + getTitle() +
				"\n Editorial: " + getEditorial() + 
				"\n Authors: ";
		for (int i = 0; i < getAuthors().length; i++) {
			detailMagazine += "\t" + getAuthors()[i] + " ";
		}
		return  detailMagazine;
	}
	
	public static ArrayList<Magazine> makeMagazineList() {
		ArrayList<Magazine> magazines = new ArrayList<Magazine>();
		String[] authors =new String[3];
		
		for (int i = 0; i < 3; i++) {
			authors[i] = "author" + i;
		}
		
		for (int i = 0; i <= 5; i++) {
			magazines.add(new Magazine("Casos y prácticas de almacenamiento "+i, new Date(), "Mecalux")) ;
		}
		
		return magazines;
	}	
}

Carlos Reyes

student•

</**
 * Hereda de {@link Publication} muestra las series disponibles pero, depende de {@link Chapter}
 * para poder establecer sus capítulos
 * 
 */>

Carlos Reyes

student•

</**
 * <h1>Publication</h1>
 * <p>
 * Es la clase base de la familia Publications
 * @author anncode 
 * version 1
 * 
 *
 */>

Carlos Reyes

student•

/**

<h1>Publication</h1>
<p>
Es la clase base de la familia Publications
@author anncode
version 1

Demetrio Del Carmen Gómez

student•

Trabajé sobre el método que valida la respuesta del usuario de AmazonUtil y sobre la descripción de la misma clase.

Luis Guzmán

student•

package com.anncode.amazonviewer.model;

import java.util.ArrayList;
import java.util.Date;

/**
 * <h1>Clase Book </h1>
 * 
 * Hereda {@link Film} e implementa {@link IVisualizable}
 * 
 * Manejo de Libros
 * 
 * @author laguz81
 * @version 1.1
 * @since 2019
 *
 */
public class Book extends Publication implements IVisualizable {
	private int id;
	private String isbn;
	private boolean readed;
	private int timeReaded;

	public Book(String title, Date edititionDate, String editorial, String[] authors) {
		super(title, edititionDate, editorial);
		// TODO Auto-generated constructor stub
		setAuthors(authors);
	}

	public int getId() {
		return id;
	}

	public String getIsbn() {
		return isbn;
	}

	public void setIsbn(String isbn) {
		this.isbn = isbn;
	}

	public String isReaded() {
		String leido = "";
		if (readed == true) {
			leido = "Sí";
		} else {
			leido = "No";
		}

		return leido;
	}

	public void setReaded(boolean readed) {
		this.readed = readed;
	}

	public boolean getIsReaded() {
		return readed;
	}

	public int getTimeReaded() {
		return timeReaded;
	}

	public void setTimeReaded(int timeReaded) {
		this.timeReaded = timeReaded;
	}

	@Override
	public String toString() {
		// TODO Auto-generated method stub
		String detailBook = "\n :: BOOK ::" + "\n Title: " + getTitle() + "\n Editorial: " + getEditorial()
				+ "\n Edition Date: " + getEdititionDate() + "\n Authors: ";
		for (int i = 0; i < getAuthors().length; i++) {
			detailBook += "\t" + getAuthors()[i] + " ";
		}
		return detailBook;
	}

	/**
	 * {@inheritDoc}
	 */
	@Override
	public Date startToSee(Date dateI) {
		// TODO Auto-generated method stub
		return dateI;
	}

	/**
	 * {@inheritDoc}
	 */
	@Override
	public void stopToSee(Date dateI, Date dateF) {
		// TODO Auto-generated method stub
		if (dateF.getTime() > dateI.getTime()) {
			setTimeReaded((int) (dateF.getTime() - dateI.getTime()));
		} else {
			setTimeReaded(0);
		}
	}

	
	public void view() {
		setReaded(true);
		Date dateI = startToSee(new Date());

		for (int i = 0; i < 100000; i++) {
			System.out.println("..........");
		}

		// Termine de verla
		stopToSee(dateI, new Date());
		System.out.println();
		System.out.println("Leíste: " + toString());
		System.out.println("Por: " + getTimeReaded() + " milisegundos");
	}

	public static ArrayList<Book> makeBookList() {
		ArrayList<Book> books = new ArrayList<Book>();
		String[] authors = new String[3];
		for (int i = 0; i < 3; i++) {
			authors[i] = "author " + i;
		}
		for (int i = 1; i <= 5; i++) {
			books.add(new Book("Book " + i, new Date(), "editorial " + i, authors));
		}

		return books;
	}

}

Laura Sofía Córdoba

student•

Clase publication

package com.lsc.amazonviewer.model;


import java.util.ArrayList;
import java.util.Date;

/**
 * Hereda de {@link Publication}
 * @author lscordoba
 * @since 2019
 *
 */

public class Magazine extends Publication {

	private int id;

	public Magazine(String title, Date editorialDate, String editorial) {
		super(title, editorialDate, editorial);
		// TODO Auto-generated constructor stub
	}

	@Override
	public int getId() {
		// TODO Auto-generated method stub
		return this.id;
	}

	@Override
	public String toString() {
		String detalMagazine = "\n :: MAGAZINE ::" + "\n Title " + getTitle() + "\n Editorial " + getEditorial()
				+ "\n Edition Date  " + getEditorialDate() + "\n Authors";
		return detalMagazine;
	}

	public static ArrayList<Magazine> makeMagazineList() {
		ArrayList<Magazine> magazines = new ArrayList<Magazine>();
		String[] authors = new String[3];
		for (int i = 0; i < authors.length; i++) {
			authors[i] = "author " + i;
		}

		for (int i = 0; i < 5; i++) {
			magazines.add(new Magazine("Magazine " + i, new Date(), "editorial " + i));
		}

		return magazines;

	}

}

Usuario anónimo

user•

Excelente :) muchas gracias

Jose Alexis Vazquez Morales

student•

voy aplicando cada tema de este curso en un proyecto personal.

package com.itsx.slasher.italikacesitmanagement.service;

import com.itsx.slasher.italikacesitmanagement.model.Administrator;
import java.util.List;

/**
 * <h2>AdministratorService</h2>
 * Servicio para el {@link Administrator} en el cual se definen
 * las acciones basicas de un CRUD
 * {@link https://www.ionos.mx/digitalguide/paginas-web/desarrollo-web/crud-las-principales-operaciones-de-bases-de-datos/}
 *
 * @author Alexis Vazquez
 * @since 2021
 * @version 1.0
 */
public interface AdministratorService {

    /**
     * {@code createAdministrator(Administrator administrator)} crea un {@link Administrator}
     * en la base de datos.
     *
     * @param administrator
     * @return true si se creo correctamente el administrador, false si ocurre algun problema
     * al generar el administrador.
     */
    boolean createAdministrator(Administrator administrator);

    /**
     * {@code removeAdministratorByFolio(long folio)} elimina un {@link Administrator} por
     * medio del folio que se pase por parametro.
     *
     * @param folio
     * @return true si el {@link Administrator} se elimino correctamente, false si no se
     * logro eliminar el {@link Administrator}.
     */
    boolean removeAdministratorByFolio(long folio);

    /**
     * {@code updateAdministrator(Administrator administrator)} es un metodo que
     * permite actualizar un {@link Administrator}.
     *
     * @param administrator
     * @return true si el {@link Administrator} se actualizo correctamente, false si
     * el {@link Administrator} no se logro eliminar
     */
    boolean updateAdministrator(Administrator administrator);

    /**
     *
     * @param folio
     * @return {@link Administrator} si se encuentra el administrador por medio del
     * folio, {@code null} si no se encontro el administrador.
     */
    Administrator getAdministratorByFolio(long folio);

    /**
     * @return una lista de administradores.
     */
    List<Administrator> getAllAdministrators();
}

Jair Israel Avilés Eusebio

student•

Estoy usando IntelliJ como editor de programa. La cuestión es que no puedo visualizar la definición de mi Java Doc, replicando el ejemplo de la clase Moviedentro del método Main.

¿Hay alguna forma de visualizar el JavaDoc correctamente en este IDE?

Isay Humberto Lucas Hernandez

student•

Muchas gracias por la respuesta Omicron 😊

Jose Luis Marin Escamilla

student•

Ya lo hice

Norman Erick Estrada Vargas

student•

excelente clase y explicación!!!

Camilo Guevara

student•

Clase Serie

package com.andycode.amazonviewer.model;

import java.util.ArrayList;

/**
 *  <h1> Serie </h1>
 * Serie una clase que hereda {@link Film}
 * <p>
 * 
 * Esta clase contiene el metodo abstracto
 * {@code view()} Que es obligatorio implementar. Ya que hereda directamente
 * de la clase abstracta Film
 * 
 * 
 * @author Andres F.B.S
 * @version 1.1
 * @since 2019
 */
public class Serie extends Film {

    private int id;
    private int sessionQuantity;
    private ArrayList<Chapter> chapters;
    // es importante hacer una coleccion de chapters[]

    public Serie(String title, String genre, String creator, int duration, int sessionQuantity) {
        super(title, genre, creator, duration);
        this.sessionQuantity = sessionQuantity;

    }

    public int getId() {
        return id;
    }

    public int getSessionQuantity() {
        return sessionQuantity;
    }

    public void setSessionQuantity(int sessionQuantity) {
        this.sessionQuantity = sessionQuantity;
    }

    public ArrayList<Chapter> getChapters() {
        return chapters;
    }

    public void setChapters(ArrayList<Chapter> chapters) {
        this.chapters = chapters;
    }
    /**
     * {@inheritDoc}
     */
    @Override
    public String toString() {

        return "\n :: SERIE :: "
                + "\n Title: " + getTitle()
                + "\n Genre: " + getGenre()
                + "\n Year: " + getYear()
                + "\n Creator: " + getCreator()
                + "\n Duration: " + getDuration();

    }
    /**
     * Este metodo nos crea una lista de series
     */
    public static ArrayList<Serie> makeSeriesList() { 

        ArrayList<Serie> series = new ArrayList<>();

        for (int i = 1; i <= 5; i++) {

            Serie serie = new Serie("Serie " + i, "Genero " + i, "Creador " + i, 1200, 5);
            serie.setChapters(Chapter.makeChaptersList(serie));
            series.add(serie);
        }

        return series;

    }
    /**
     * {@inheritDoc }
     */
    
    @Override
    public void view() {
        setViewed(true);
        
    }
}

Documentación de Clases Heredadas en Java

Introducción al Curso

Java SE Avanzado: Programación Modular y Persistencia con JDBC

Clases avanzadas

Clases Abstractas y Polimorfismo en Java: Avances y Aplicaciones

Reducción de Código con Clases Abstractas en Java

Sobrescritura de métodos en clases derivadas en Java

Polimorfismo y Abstracción en Clases Java

JavaDocs

Generación de Documentación Java con Javadocs

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

Documentación de librería Report en Java SE