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.
