Documentación de Código Java: Javadoc y Comentarios Esenciales

Tipos de Comentarios en Programación

Comentarios de una Línea (//)

• Comienzan con // y terminan al final de la línea.
• Se usan para documentar código que no se desea incluir en la documentación externa generada por Javadoc.

Comentarios Multilínea (/* ... */)

• Comienzan con /* y terminan con */.
• Pueden extenderse a lo largo de varias líneas (a menudo, cada línea intermedia comienza con *).
• Útiles para bloques de comentarios extensos o para deshabilitar temporalmente bloques de código (ej. "mantenimiento de código obsoleto 'por si acaso'").

Javadoc: Documentación de APIs en Java

La Necesidad de Javadoc

• Generar documentación de una API manualmente es tedioso y propenso a errores.
• El paquete de desarrollo Java (JDK) incluye la herramienta javadoc para generar un conjunto de páginas web (documentación HTML) a partir de los ficheros de código fuente.
• Actúa como un contrato entre el programador de la clase/método y el usuario, ofreciendo una referencia rápida sobre las funcionalidades de una clase, paquete o interfaz.

¿Qué es Javadoc?

• Es una utilidad de Oracle para la generación de documentación de APIs en formato HTML a partir de código fuente Java.
• Javadoc es el estándar de la industria para documentar clases en Java.

Sintaxis y Estructura de Comentarios Javadoc

• Javadoc procesa comentarios con una sintaxis especial: deben comenzar con /** y terminar con */.
• Incluyen una descripción principal y pueden contener etiquetas especiales (tags).
• Estas etiquetas se escriben dentro de un comentario Javadoc (/** ... */) al principio de cada clase, miembro o método, según el elemento que se desee describir.

Ejemplo de Estructura Javadoc

/**
 * Parte descriptiva.
 * Puede consistir en varias frases o párrafos.
 *
 * @etiqueta texto específico de la etiqueta
 */

Tipos de Etiquetas (Tags) Javadoc

• Block Tags: Ubicados después de la descripción principal. Se inician con @tag.
• Inline Tags: Ubicados dentro de la descripción principal o en las descripciones de los block tags. Se encierran entre llaves: {@tag}.

Etiquetas Javadoc Comunes

Para Clases e Interfaces

• @author: Nombre del autor.
• @version: Identificación de la versión y fecha.
• @see referencia: Añade enlaces de referencia a otras clases, métodos o partes de la documentación.

Para Constructores y Métodos

• @param nombre_parámetro: Descripción de su significado y uso.
• @return: Descripción de lo que devuelve el método.
• @exception nombre_excepción: Excepciones que pueden lanzarse (sinónimo de @throws).
• @throws nombre_excepción: Excepciones que pueden lanzarse (sinónimo de @exception).
• @deprecated: Indica que el uso del elemento está desaconsejado.

Etiquetas Inline Específicas

• {@link package.class#member label}: Crea un enlace a otra parte de la documentación (clase, método, miembro).

Copiado de Documentación con {@inheritDoc}

• {@inheritDoc}: Permite copiar la documentación de un elemento de nivel superior.
• Implícito (automático): La herramienta Javadoc toma la descripción o el tag de la clase o interfaz de nivel superior.
• Explícito: Copia la documentación del elemento de nivel superior inmediato.