¿Qué es la documentación técnica? Documentar es agregar cierta información al código que nos permitirá conocer detalles importantes de éste y con lo cual se espera tener mayor facilidad a la hora de leer las instrucciones de la aplicación ya sea por parte del creador o por otra persona.
La documentación no es un lujo(*) sino una necesidad por lo tanto, es sumamente importante de considerar a la hora de hacer un software, ya que es común que los programas sufran cambios a lo largo de su “vida” al adaptarse a nuevos escenarios, por lo tanto poner líneas con esta información ayudará a repararlo y modificarlo.
(*) Con lujo me refiero a que sea algo de más, algo de adorno.
Ejemplo de aplicación de documentación técnica tomado de http://es.wikipedia.org/wiki/Javadoc
¿Y qué es lo que comúnmente se documenta? Comenzar documentando el propósito del software, el desarrollador y la fecha de creación no sería una mala idea. Tampoco lo sería comentar la funcionalidad de cada uno de los métodos o clases. Todo comentario es bien recibido siempre y cuando aporte.
La documentación bien podría hacerse sólo en el código y ya, sin embargo esto no sería del todo adecuado teniendo herramientas que permiten manejar toda la documentación en un sitio aparte de una forma clara y ordenada.
Hay decenas de generadores de documentación (Sandcastle, NDdoc, Doxygen, Natural Docs), cada uno con sus requerimientos y especificaciones, sin embargo me centraré en javadoc ya que es el que voy a utilizar para mi proyecto.
Javadoc
Es un recurso de Oracle que nos permite generar la documentación en formato HTML de una aplicación en Java.
Dentro de un código, Javadoc toma aquellos comentarios que cuentan con las marcas especiales especificadas por dicho programa y construye un archivo HTML en el que se maneja toda esa información como toda la documentación estándar de Java provista por SUN.
He aquí el API de Java provista por Oracle. Éste es un claro ejemplo de cómo se generaría su documentación.
¿Y cuáles son esas marcas especiales?
Javadoc toma en consideración aquellos comentarios que empiecen con /** y terminen con */, por lo tanto todo lo que escribamos dentro de esos signos será material de trabajo para Javadoc. A la vez, dentro de estos comentarios podremos utilizar instrucciones HTML y ciertas palabras reservadas generalmente precedidas del “@”, y que son muy útiles para la documentación de datos relevantes.
A continuación se presentarán algunas de las palabras reservadas comúnmente utilizadas:
Una vez expuestos los identificadores se podrá ser capaz de entender el ejemplo mostrado en la parte superior de esta entrada.
¿Cómo se consigue Javadoc?
Javadoc viene incluido en el JDK.
He aquí la liga para descargar el Java Development Kit en caso de no contar con éste.
También se puede descargar de forma aislada en este link:
¿Cómo se ejecuta Javadoc?
Javadoc se ejecuta simplemente haciendo uso de estas líneas en el cmd:
javadoc [paquete] archivo.java, ...
Al momento de hacer lo anterior se crearán todos los files HTML así que hay que cerciorarse de generarlos en una carpeta aparte para que no se mezclen con los files del código.
FUENTES
Ok. Recuerda que la indicación era hacer el reporte de forma gráfica (con mapa conceptual, cuadro sinóptico, etc.)
ResponderEliminarCalificación: 80 (4/5)
No seas culera, pongale 100 alv :v
EliminarNo seas culera, pongale 100 alv :v
Eliminar