¿Qué es la documentación en Java? HTML

La documentación en un proyecto es una parte fundamental a futuro ya que cuando se programa una clase, se debe generar la documentación lo suficientemente detallada haciendo uso del Javadoc, con el fin de que otros programadores sean capaces de usarla sólo con su interfaz. No debe existir necesidad de leer o estudiar su implementación, lo mismo que nosotros para usar una clase del API Java no leemos ni estudiamos su código fuente.

[Documentación en Java] (https://javadesdecero.es/basico/tipos-comentarios-ejemplos/)

¿Qué es el Javadoc?

Es una utilidad de Oracle que la mayoría de IDEs utilizan para la generación de comentarios y documentación de APIs en formato HTML a partir de código fuente Java. • La herramienta Javadoc extrae esos comentarios especiales y genera páginas HTML para ser vistas desde el navegador. De esta manera facilitamos poder navegar de una clase a otra.

La documentación de Java

• Los diseñadores de Java definieron un método sencillo para generar la documentación de las clases y métodos:
• La documentación se inserta en el mismo fichero que el código (en forma de comentarios)

Veamos en primer lugar qué se debe incluir al documentar una clase:

a) Nombre de la clase, descripción general, número de versión y nombres de autores.

b) Documentación de cada constructor o método (especialmente los públicos) incluyendo: nombre del constructor o método, tipo de retorno, nombres y tipos de parámetros si los hay, descripción general, descripción de parámetros (si los hay)y descripción del valor que devuelve.

¿Qué hay que documentar?

Hay que añadir explicaciones a todo lo que no es evidente.
No hay que repetir lo que se hace, sino explicar por qué se hace.

Y eso se traduce en algunos ejemplos como:

• ¿De qué se encarga una clase o un paquete?
• ¿Qué hace el método o constructor en caso que se utilice?
• ¿Cuál es el uso esperado del método?
• ¿Para qué se usa una variable?
• ¿Cuál es el uso esperado de una variable?
• ¿Qué algoritmo estamos usando, de dónde lo hemos sacado?
• ¿Qué limitaciones tiene el algoritmo y la implementación?
• ¿Qué se debería mejorar... si hubiera tiempo?

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

• Una clase.
• Un atributo.
• Un método.

Un ejemplo de etiquetas en comentarios:

Ejemplo
/**
*Esta clase contiene los atributos y métodos de un empleado
*@author Mario Celis
*@version 1.0
*@see Persona
*/

Para la documentación en Java

Comentarios en java

Recordar que los comentarios javadoc son /** ... */. Se utiliza el carácter @ como anotación especial:

• Para describir las etiquetas de documentación.
• Los comentarios se deben colocar justo antes del elemento a documentar.
• Se permite añadir elementos HTML a la documentación para enriquecer su presentación