Una de las cosas que tiene
Spring por las cuales creo me ha comenzado a gustar es que, tiene todo un conjunto de proyectos al rededor del framework principal.
Solo tenemos que ver el listado dentro del sitio oficial de
Spring para darnos cuenta de esto:
De entre todos estos proyectos, le he dado una revisada al Spring BeanDoc y me ha encantado ya que existen un par de cosas que he aprendido sobre la documentacion:
- Nunca es suficiente la documentación que dejas sobre tu código.
- Mientras mas documentación legible dejes, menos te maldecirá la persona que lo retome.
- Dicha persona puedes ser tu mismo si vuelves tiempo después al mismo proyecto :P
Por eso es que me ha encantado este subproyecto de Spring, ya que, como su nombre lo dice, ayuda a documentar la información de los Beans que utilizas en tu aplicación.
El presente documento muestra cuales son los pasos para poner en marcha y utilizar las bondades de esta herramienta:
Paso 1. Accedemos a la página principal del proyecto y descargamos la última distribución estable.
http://spring-beandoc.sourceforge.net/
Figura 1. Home de Spring BeanDoc
Este es el enlace para descargar la version 0.8.1
http://sourceforge.net/project/showfiles.php?group_id=209187
Figura 2. Descarga desde sourceforge
Descargamos el archivo: spring-beandoc-0.8.1-bin.zip
Una vez descargado, al descomprimirlo obtenemos una estructura como la siguiente:
Figura 3. Estructura de carpetas de Spring BeanDoc.
La página principal nos pide que instalemos adicionalmente un programa que nos ayuda a generar los grafos de la documentación.
Paso 2. Instalación de GraphViz.
Visitamos http://graphviz.org/
Figura 4. Home de graphviz.org
El enlace para descargar la versión actual - para Windows - es:
http://graphviz.org/Download_windows.php
Descargamos el archivo:graphviz-2.16.1.exe
Lo ejecutamos:
Figura 5. Instalación de Graphviz.
Al terminar la instalacion, debe quedarnos una estructura como la siguiente:
Figura 6. Estructura de carpetas de Graphviz.
Paso 3. Proceso de verificación.
A grandes rasgos, Spring BeanDoc genera la documentación y los grafos a partir de los XML's de configuracion de nuestros spring Beans.
La siguiente imagen intenda ilustrar esto:
Figura 7. Diagrama de bloques de Spring BeanDoc.
La ubicación de esos XML's y otros parámetros de configuración se definen en un archivo .properties y a partir de él Spring BeanDoc se encarga de hacer el trabajo sucio.
Aquí las modificaciones que realice al archivo petclinic-beandoc.properties que se ubica dentro de la carpeta de examples:
- Se definio la ubicación de los XML's de entrada
- Se definio la carpeta de salida
- Se definio la ubicación del archivo dot.exe que genera los grafos.
# ----------------------------------------------------------------------------
# Petclinic beandoc.properties configuration file.
#
# See the 'template-beandoc.properties file for annotated examples of what
# you can configure.
# ----------------------------------------------------------------------------
input.files=C:/WorkArea/dev/spring/beandoc/spring-beandoc-0.8.1/samples/petclinic/*.xml
output.dir=output/petclinic
html.title=Petclinic Application Context
html.cssUrl=wheat.css
compiler.dotExe=C:/Program Files/Graphviz2.16/bin/dot.exe
graphs.colourBeans[.*Proxy$]=#badbad
graphs.ignoreBeans[0]=^org\.springframework.*Property.*Configurer
graphs.ignoreBeans[1]=.*MessageSource
graphs.rankBeans[0]=.*DataSource
graphs.outputType=png
# ----------------------------------------------------------------------------
Ya que tenemos definido nuestro archivo properties, solo necesitamos ejecutar la clase que realiza la transformación:
Esta es:
org.springframework.beandoc.client.BeanDocClient
Esa clase se encuentra en el jar: spring-beandoc-0.8.1.jar y recibe un como parametro el archivo .properties.
Así, para generar nuestra documentación a partir del ejemplo del petclinic tenemos que debemos ejecutar:
[INSTALL_BEANDOC]/samples> java org.springframework.beandoc.client.BeanDocClient --properties petclinic-beandoc.properties
[Asegurate de agregar todos los jars ubicados en la carpeta [INSTALL_BEANDOC]\lib para que la compilación no se queje con un NoClassDefFoundError o en su defecto ejecutalo con la opcion -cp]
Y listo!!!
Figura 8. Documentación generada con la herramienta.
Hemos generado nuestra documentación de nuestro proyecto spring a partir de nuestros archivos XML utilizando la herramienta BeanDoc.
Saludos!!!
RuGI
Isaac Ruiz Guerra.
martes, septiembre 25, 2007 at 2:57AM