ed-b1 instalación y uso de entornos

javadoc

eugeniaperez.es

UT 4: el lenguaje java

Javadoc

documentación de programas... en java

eugeniaperez.es

UT 4: el lenguaje java

Javadoc

¿PORQUÉ ES IMPORTANTE DOCUMENTAR...?

eugeniaperez.es

• Perder el tiempo
• Mejor calidad en los programas
• Mejorar el mantenimiento

2 premisas...

UT 4: el lenguaje java

Javadoc

javadoc

eugeniaperez.es

http://docs.oracle.com/javase/7/docs/api/java/lang/String.html

UT 4: el lenguaje java

Javadoc

¿QUÉ DEBEMOS DOCUMENTAR...?

eugeniaperez.es

UT 4: el lenguaje java

Javadoc

tipos de comentarios

eugeniaperez.es

javadoc

Comienzan con  "/**" y terminan por "*/".

una línea

Comienzan con "//" y terminan con la línea

tipo C

Comienzan con  "/*" y terminan con "*/".

UT 4: el lenguaje java

Javadoc

propósito de  cada tipo de comentarios

eugeniaperez.es

javadoc

Para generar documentación externa.

una línea

Código que no necesitamos que aparezca en la documentación externa. 

tipo C

Para documentar código desactualizado. 

UT 4: el lenguaje java

Javadoc

¿cuándo debemos poner comentarios...?

eugeniaperez.es

Por obligación (javadoc):

1. al principio de cada clase
2. al principio de cada método

UT 4: el lenguaje java

Javadoc

¿cuándo debemos poner comentarios...?

eugeniaperez.es

Por conveniencia (una línea):

3. ante cada variable de clase si su función no es evidente

4. al principio de fragmento de código no evidente

5. a lo largo de los bucles

UT 4: el lenguaje java

Javadoc

¿cuándo debemos poner comentarios...?

eugeniaperez.es

Y por si acaso (una línea):

6. siempre que hagamos algo raro

7. siempre que el código no sea evidente

UT 4: el lenguaje java

Javadoc

javadoc

eugeniaperez.es

UT 4: el lenguaje java

Javadoc

documentación de clases

eugeniaperez.es

• @author
• @version
• @see

UT 4: el lenguaje java

Javadoc

documentación de clases

eugeniaperez.es

• Además de eso dentro de los comentarios podemos meter etiquetas HTML básicas… 

• <b>Esto saldría en negrita</b>
• <i>Esto sacaría el texto en cursiva</i>
• {@link OtraClase} : genera un enlace a la documentación de otra clase

UT 4: el lenguaje java

Javadoc

documentación de constructores y métodos

eugeniaperez.es

• @param
  una por argumento de entrada
• @return
  si el método no es void
• @exception ó @throws
  una por tipo de Exception que se puede lanzar
   

UT 4: el lenguaje java

Javadoc

EJECUCIÓN DE JAVADOC EN ECLIPSE

eugeniaperez.es

• Vamos al Menú, Project > Generate Javadoc
• Es imprescindible establecer la ruta del comando javadoc.exe. 
• Personalizamos opciones.

UT 4: el lenguaje java

Javadoc

¿tengo que codificar y documentar en inglés...?

eugeniaperez.es

• Capricho de la profesora
• Programas más naturales
• Mayor difusión y visibilidad