miércoles, 16 de febrero de 2011

Documentación y herramientas de desarrollo

Clase Programación Orientada a Objetos


Sesión #4 Documentación y herramientas de desarrollo.


Diana Jazmi Rojas Alvarado
Matrícula: 1219382


Hola chicos en la información que encontré sobre la documentación de programas fue la siguiente.


Documentar el código de un programa es añadir suficiente información como para explicar lo que hace, punto por punto, de forma que no sólo los ordenadores sepan qué hacer, sino que además los humanos entiendan qué están haciendo y por qué.
Es  una necesidad que sólo se aprecia en su debida magnitud cuando hay errores que reparar o hay que extender el programa con nuevas capacidades o adaptarlo a un nuevo escenario.
Todo programa que tenga éxito será modificado en el futuro, bien por el programador original, bien por otro programador que le sustituya. Pensando en esta revisión de código es por lo que es importante que el programa se entienda: para poder repararlo y modificarlo.


En caso de mi proyecto utilizare java, por lo cual busque informacion para este.


El nombre de la herramienta es javadoc que  es una utilidad de Sun Microsystems para la generación de documentación de APIs en formato HTML a partir de código fuente Java.



Para que javadoc pueda generar los textos HTML es necesario que se sigan unas normas de documentación en el fuente, que son las siguientes:
  • Los comentarios de documentación deben empezar con /** y terminar con */. 
  • Se pueden incorporar comentarios de documentación a nivel de clase, a nivel de variable (dato miembro) y a nivel de método.
  • Se genera la documentación para miembros public y protected.
  • Se pueden usar tags para documentar ciertos aspectos concretos como listas de parámetros o valores devueltos.

Algunas etiquetas que podemos utilizar para la documentación son:

Clases e Interfaces 
version @ 
información sobre esta versión version @
author @ 
información sobre el autor o autores author @
Variables 
Comentarios con HTML 
deprecated , @link, @ see @ 
descripción-opcional @serial  
por defecto serializables.

miembro # see @
,...) Tipo ,  Tipo ( metodo # see @
Clases (o miembros de la clases) del mismo paquete o de  
paquetes importados.
@see referencia 
Permite referirse a la documentación de otras clases 
con enlaces HTML See Also  Genera una sección. 
} nombre etiqueta {@link
pero se puede poner dentro de una línea see  Similar a @. 
texto since @ 
En el texto se indica desde cuando está disponible esta caracteristica.

Esto es solo alguna explicación breve o al menos es lo que ocuparé en mi proyecto
Espero y les sirva de algo la información.


2 comentarios:

  1. Me hubiera gustado tener una explicación sobre cómo se corre la herramienta. Te pongo 4.

    ResponderEliminar
  2. Te tengo en la lista del taller pero ahí andas sacando puro NP: ¿Estás inscrita en esa también o debería quitarte de la lista mejor?

    ResponderEliminar