A quines interesa el cdigo fuente?

Autores del propio cdigo Otros desarrolladores del proyecto Clientes de la API del proyecto

Por qu documentarlo?

Mantenimiento Reutilizacin

Qu documentar?

Obligatorio ( /** Javadoc */ ) Clases y paquetes Constructores, mtodos y atributos Conveniente ( // una sola lnea /* varias lneas */ ) Fragmentos no evidentes Bucles, algoritmos.

Generar documentacin de una API a mano es tedioso y propenso a errores Gran cantidad de pequeos detalles Sincronizacin de cdigo fuente y documentacin Duplicidad de esfuerzos (tipos, nombres. . . ) Combinar cdigo fuente con documentacin Generar documentacin desde el cdigo La documentacin embebida en el cdigo tiende a ser ms correcta

Javadoc genera documentacin en HTML

Comentarios con una sintaxis concreta, que se ubican antes de las clases, interfaces, constructores, mtodos y atributos a documentar.

Qu son :

Estructura

/**

*
* Descripcin principal * * * Tags (etiquetas) * * */

La primera frase de cada comentario Javadoc debe ser una frase resumen con una descripcin concisa y completa, terminada en punto, y seguida de un espacio.

Preferible el uso de la tercera persona.

Devuelve el ndice del primer elemento... Devolvemos el ndice del primer elemento...

Empezar con un verbo la descripcin de los mtodos.

Omitir el sujeto cuando es obvio.

@param peer nombre del peer @param peer parmetro con el nombre del peer

Aplicable en las clases, no se repite para cada mtodo, a no ser que algn mtodo haya sido escrito por otra persona.

Describe informacin del autor (es).

Si son varias personas se escriben los nombres separados por comas o se repite el indicador, segn se prefiera

Aplicable normalmente en clases pero tambin se usa para mtodos.

Describe la versin y fecha. El texto no tiene que tener formato especial

Aplicable a parmetros de constructores y mtodos.

Describe los parmetros del constructor mtodo.

nombre: idntico al nombre del parmetro.

Aplicable a mtodos.

Describe el valor de retorno del mtodo.

Incluir descripcin de valores de retorno especiales: null

Aplicable a constructores y mtodos.

Nota: @exception y @throws se pueden usar indistintamente.

Describe las posibles excepciones del constructor mtodo.

Un @throws por cada posible excepcin.

Aplicable a clases, interfaces, constructo res, mtodos, atributos y paquetes.

Aade enlaces de referencia a otras partes de la documentacin.

Referencia: (#mtodo(); clase#mtodo(); paquete.clase; paquete.clase#mtodo().