Los comentarios en Java HTML

Son una gran herramienta para documentar nuestro código y hacerlos más entendibles para terceros. El uso principal de los comentarios en cualquier lenguaje de programación es una herramienta que sirve para apoyar la documentación de los programas que desarrollamos y así facilitar su posterior comprensión.

Estas líneas de código, que no se toman en cuenta al momento de ejecutar el programa, por lo tanto no están sujetas a restricciones de sintaxis ni nada similar.

Por ejemplo es muy común usar las líneas de comentarios, para dar una breve explicación de cómo funciona cierta parte de un código, lo cual permite identificar todo con mayor rapidez.

Tipos de comentarios

Comentarios en Java de una sola línea

Comienzan por un doble slash "//", al colocar el doble slash en cualquier línea de código, todo lo que haya de ahí en adelante en dicha línea será tomado como comentario, ten en cuenta que el doble slash solo convierte en comentario al texto que pertenezca a su misma línea, las líneas de abajo de este, no se verán afectadas

Comentarios en Java de múltiples líneas

Estos comentarios van cerrados entre "/*" y "*/", es decir comienzan donde se ponga "/*" y terminan donde esté el "*/", siendo esto una manera mucho más sencilla en vez de esta añadiendo doble slash "//" a cada línea. A diferencia de los comentarios de una sola línea, al poner el símbolo "/*" todo el código que haya tanto en la misma línea, como en las línea posteriores de este se convertirán en comentarios hasta que pongamos el "*/" para indicar que hemos cerrado los comentarios

Comentarios de documentación en Java (Javadoc):

Son de especial utilidad al momento de documentar no sólo el código fuente, sino el proyecto como tal. Estos comentarios van cerrados entre "/**" y "*/", es decir comienzan donde se ponga "/**" y terminan donde esté el "*/".Cabe resaltar que estos comentarios a diferencia de los comentarios de múltiples líneas, inician con "/**" (doble asterisco) en lugar de "/*" (un solo asterisco). Adicionalmente, se recomienda que cada línea que compone el bloque de comentarios inicie con "*".

Estos comentarios además requieren de algunos "componentes" para indicar los componentes del código fuente, tales como parámetros, tipos de retorno, entre otros. Estos "componentes" se normalmente se preceden por un @, por ejemplo para indicar un parámetro de una función de usa @param, o para indicar detalles sobre el retorno se usa @return.

Tipo	Notación	Ejemplo
En una línea	Comienzan con los caracteres // y terminan con la línea	//Recursividad
En múltiples líneas	Empieza con /* se escriben varias líneas y terminan con los caracteres */	/*Este es un ciclo for */
Javadoc	Comienzan con los caracteres /**, y en varias líneas al inicio se agrega * y terminan con los caracteres "*/"	/*Esta línea
		*no
		* se
		ejecuta*/

Etiquetas de javadoc

La herramienta javadoc reconoce las siguientes etiquetas:

Etiqueta	Descripcion	Syntax
@author	Agrega el autor de una clase.	@author name-text
{@code}	Muestra texto en fuente de código sin interpretar el texto como marcado HTML o etiquetas javadoc anidadas.	{@code text}
{@docRoot}	Representa la ruta relativa al directorio raíz del documento generado desde cualquier página generada.	{@docRoot}
@deprecated	Agrega un comentario que indica que esta API ya no debe usarse.	@deprecated deprecatedtext
@exception	Agrega un subtítulo Throws a la documentación generada, con el nombre de la clase y el texto de descripción.	@exception class-name description
{@inheritDoc}	Hereda un comentario de la clase heredable o interfaz implementable más cercana .	Inherits a comment from the immediate surperclass.
{@link}	Inserta un enlace en línea con la etiqueta de texto visible que apunta a la documentación del paquete, la clase o el nombre de miembro especificados de una clase referenciada.	{@link package.class#member label}
{@linkplain}	Idéntico a {@link}, excepto que la etiqueta del vínculo se muestra en texto sin formato que en fuente de código.	{@linkplain package.class#member label}
@param	Agrega un parámetro con el nombre de parámetro especificado seguido de la descripción especificada a la sección "Parámetros".	@param parameter-name description
@return	Agrega una sección "Devoluciones" con el texto de descripción.	@return description
@see	Agrega un encabezado "Ver también" con un enlace o entrada de texto que apunta a una referencia.	@see reference
@serial	Se utiliza en el comentario del documento para un campo serializable predeterminado.	@serial field-description
@serialData	Documenta los datos escritos por los métodos writeObject () o writeExternal ().	@serialData data-description
@serialField	Documenta un componente ObjectStreamField.	@serialField field-name field-type field-description
@since	Agrega un encabezado "Desde" con el texto desde especificado a la documentación generada.	@since release
@throws	Las etiquetas @throws y @exception son sinónimos.	@throws class-name description
{@value}	Cuando se usa {@value} en el comentario de documento de un campo estático, muestra el valor de esa constante.	{@value package.class#field}
@version	Agrega un subtítulo "Versión" con el texto de la versión especificado a los documentos generados cuando se usa la opción -version.	@version version-text

Nota Importante

Los comentarios de documentación no deben colocarse en el interior de la definición de un método o constructor, ya que Java asocia los comentarios de documentación con la primera declaración después del comentario

ANOTACIONES Javadoc

Generales

• @see referencia. Realiza un enlace. Ejemplos de referencia son: #metodo(); clase#metodo(); paquete.clase; paquete.clase#metodo();
• @since. Indica en la versión que apareció este elemento respecto a la secuencia de versiones aparecidas a lo largo del tiempo

Paquetes

• @see, @since
• @deprecated. Indica que este elemento es antiguo y que no se recomienda su uso porque posiblemente desaparecerá en versiones posteriores. Se debe indicar la alternativa correcta

Clases e interfaces

• @see, @since, @deprecated
• @version. Versión y fecha
• @author. Nombre del autor

Variables y constantes

• @see, @deprecated

Métodos

• @see, @since, @deprecated
• @param. Definición de un parámetro, es obligatorio. *@param parámetro descripción
• @return. documenta el dato devuelto, es obligatorio. *@return descripción
• @throws. Excepción lanzada por el método. *@throws clase descripción