La gran ventaja que tiene esto es que simplemente con hacer unos comentarios de una forma un tanto especial podemos conseguir que todo aquel que lea el código fuente lo entienda mucho más rápido. Además, como la documentación se genera en HTML siempre la podremos colgar en una página web si fuese necesario.

Aquí dejo una mini-guía de referencia rápida.

• Una sección de Javadoc se inicia con /** y se acaba con */
• Primero se hace una descripción de la función y luego:
• @author – Nombre del autor
• @deprecated – Indica que el método ha quedado en desuso
• @exception – Documenta una excepción – sinónimo de @throws
• @param – Cada parametro debe ser explicado con este tag
• @return – Documenta el valor de retorno de una función
• @see – Documenta una asociación con otro método o clase
• @since – Indica la version o cuando se ha añadido un método a la clase
• @throws – Documenta una excepción – sinónimo de @exception
• @version – Identifica la versión de una clase o método

Básicamente con eso debería llegar para empezar, dejo tabién un pequeño ejemplo en código fuente por si a alguien no le ha quedado del todo claro.


/**
* Suma dos enteros
*
* @param a Primer entero a sumar
* @param b Segundo entero a sumar
* @return La suma de los enteros a y b
* @author Santiago W. Fernández Lorenzo
*/
int suma(int a, int b) {
return (a+b);
}


PD: Os dejo también un enlace a la página oficial de JavaDoc.