javadoc con UML

Hurgando por ahí me he encontrado con UMLGraph, una herramienta que genera gráficos UML a partir de unos textos que los describen. Lo bueno es que, al menos para el diagrama de clases, el texto que describe el diagrama UML es exactamente igual que un fuente java. Dicho de otra forma, si ponemos en el fichero "class UnaClase extends UnPadre {}", obtendremos un diagrama con una cajita UnaClase que hereda (flechita con triángulo) de una cajita UnPadre. Puedes ver el ejemplo aquí. Esto lo hace ideal para generar los gráficos UML de clases a partir de código fuente ya hecho.

Otro punto interesante es que viene con la posibilidad de invocar javadoc usando UMLGraph, de forma que en nuestro javadoc se generaría diagramas de clases incrustados. UMLGraph viene con un doclet que se puede usar desde el comando javadoc de java y de esta forma, javadoc generará la documentación de la forma habitual, pero incluyendo un gráfico de UML. En la descripción de un package, pondrá todas las clase incluidas en ese package y las relaciones entre ellas. En la descripción de una clase pondrá un dibujo de dicha clase con las relaciones (herencias, dependencias, etc) con otras clases del paquete o de otros paquetes. En la figura puedes ver un ejemplo de javadoc generado con el doclet de UMLGraph.

javadoc con grafico UML

Un detalle a tener en cuenta es que para que UMLGraph pueda generar los ficheros gráficos es necesario tener instalado previamente GraphViz.

En el diagrama de clases podrían configurarse muchas cosas, poner notas asociadas a las clases, poner otro tipo de cajas que no sean de clases, métodos que deben o no mostrarse, etc. La pega de ello es que iría configurado en código a base de anotaciones, por lo que el código quedaría algo "guarreado" para luego ver el dibujo bonito.

También pueden hacerse diagramas de secuencia, pero desgraciadamente la sintaxis del fichero de texto que lo describe ya no es java, así que no deja de ser una forma alternativa de hacer el diagrama. Puede ser interesante, por ejemplo, si guardamos los diagramas de secuencia en un sistema de control de versiones (como subversion). Siempre ocupa menos y es más interesante para ver diferencias con versiones anteriores un fichero de texto que no un gráfico o un proyecto entero de alguna herramienta compleja de generación de gráficos UML (Together, Rational,…).

Y otra cosa que a mí siempre me viene bien, es que UMLGraph está subido al repositorio ibiblio de maven y tiene plugin para el mismo. De esta forma, configurando el fichero pom.xml de nuestro proyecto maven (en concreto, configurando el plugin de javadoc para que use el doclet de UMLGraph), podemos generar el javadoc con gráficos UML directamente desde maven. La configuración sería algo parecido a esto

<reporting>
   <plugins>
      <plugin>
         <artifactId>maven-javadoc-plugin</artifactId>
         <configuration>
            <source>1.5</source>
            <aggregate>true</aggregate>
            <doclet>gr.spinellis.umlgraph.doclet.UmlGraphDoc</doclet>
            <docletArtifact>
               <groupId>gr.spinellis</groupId>
               <artifactId>UmlGraph</artifactId>
               <version>4.6</version>
             </docletArtifact>
             <additionalparam>
                    -inferrel -inferdep -quiet -hide java.*
                    -collpackages java.util.* -qualify
                    -postfixpackage -nodefontsize 9
                   -nodefontpackagesize 7
             </additionalparam>
          </configuration>
       </plugin>
    </plugins>
</reporting>

Con esto, un simple mvn javadoc:javadoc nos generaría la documentación javadoc de nuestro proyecto maven, gráficos UML incluidos.

 

Problemillas con StarUML

En ocasiones y para hacer diagramas UML rápidamente, usamos StarUML. Es una aplicación gratuita y sencilla para hacer diagramas UML rápidamente. Sin embargo, tiene una serie de problemas que nos han traido de cabeza hasta que hemos descubierto los motivos y hemos podido evitarlos.

El problema principal es con el idioma español de Windows y los puntos/comas decimales de los números. La herramienta no entiende la coma decimal de español y da los siguientes problemas:

  • No permite hacer ingeniería inversa. Si se intenta, empieza a dar errores con estos temas.
  • No permite el "layout" automático de los diagramas (que automáticamente recoloque las figuras para que queden más ordenadas).

Buscando por internet, encontramos un LocaleFix.bat. Si arrancamos StarUML con este bat, supuestamente se corrigen estos problemas. Sin embargo, usarlo trae otros problemas.

  • Al abrir con LocaleFix.bat, es posible que algunas etiquetas de los diagramas de secuencia (y otras) se descoloquen, quedando un poco más arriba o abajo de lo normal.
  • Si volvemos a poner en su posición esas etiquetas descolocadas, es posible que la siguiente vez que abramos el proyecto esas etiquetas no sean visibles (siguen estando las flechas, pero no los textos). En esta situación, si intentamos exportar el gráfico a un fichero jpg nos dará un error y no lo hará.

Al final, la solución, es andar con mucho cuidado:

  • Abrir StarUML sin usar el LocalFix.bat para el trabajo normal.
  • Abrir StarUML con LocaleFix.bat si queremos hacer una ingeniería inversa, pero sólo para eso y sin tocar nada más. Una vez hecha la ingeniería inversa, se salva el proyecto y se rearranca StarUML sin LocaleFix.bat