Generar comentarios dentro del código

Java tiene una herramienta que ayuda a generar documentación mediante un estándar llamado JavaDoc que permite generar la documentación externa en forma de página web. Esta página web se encuentra en forma de archivos html, css y js de manera local y pueden ser publicadas en la web con herramientas como Netlify

Comentar el código

Para generar los comentarios dentro del código se utiliza el auto-completado presente en la mayorías de IDEs de hoy en día, mediante la combinación del texto /** y la tecla Enter, de esta manera se genera una plantilla que se puede llenar.

La plantilla que genera el IDE puede contener diferentes valores que ayuda a auto-completar, entre los que podemos encontrar:

@return: el valor que retorna la función
@throws: las excepciones que genera la función
@param [var]: cada uno de los parámetros que recibe la función, este se repite y viene acompañado con el nombre de la variable que se va a comentar.

Generar JavaDoc

En el momento en que el código está comentado, se puede generar la documentación con JavaDoc, la cual se genera en forma de página web de manera local. Mediante la opción Tools > Generate JavaDoc...

Eso genera una ventana de configuración que permite seleccionar el sitio dentro de nuestro equipo local donde se quiere guardar los archivos generados mediante el campo Output directory

La herramienta crea todos los archivos en la carpeta seleccionada, por lo que se recomienda que la capeta seleccionada esté vacía, luego de generarlo el sistema abre automáticamente la página web generada.

Publicar la documentación generada

Los archivos generados por JavaDoc permiten compartir de manera pública o privada la documentación del proyecto, por lo que se puede utilizar herramientas como Netlify para publicarlo sin coste extra.

Publicar en Netlify

Para esto se puede dirigir al sitio web https://www.netlify.com y crear un usuario, iniciar sesión y luego dirigirse a apartado Sites. El cual en la parte inferior tiene habilitada la opción de publicar un sitio web con solo "arrastrar y soltar" una carpeta en el espacio punteado.

Y esto genera una dirección web finalizada en netlify.app que es pública y puede ser compartida ya que se encuentra publicada en internet.

Reemplazar publicación

Si se desea agregar una actualización a la página web generada, se puede realizar de la misma manera que la publicación, con diferencia de que se debe hacer en el aparado Deploy