A Better Way for UML Management
Join the DZone community and get the full member experience.
Join For FreeWhile aiming at blueMarine 1.0 for the end of the year, the effort is
being put not only to stability and performance, but also on cleaning
up the APIs in order to have a polished and stable version that others
might use.
To that end, I'm finding an excellent tool in the book "Practical API Design: Confessions of a Java Framework Architect"
by Jaroslav Tulach (I've not finished it yet, I'll post a review as
soon as I complete reading it), but my concern is also to write the
proper documentation for users. One of the problems is with the UML
diagrams - so far I've used the UML editor in NetBeans, but keeping
them up-to-date is really time expensive, especially after some heavy
refactoring.
Meera Subbarao and Geertjan Wielenga have written about a better solution (start reading this article on DZone): using a custom Javadoc doclet (UmlGraphDoc)
to automatically generate the UML diagrams and put there in the
generated javadocs (of course, you can even take the diagrams alone and
reuse them on other documents). They explained the process in details
with some examples about customizing build.xml, here I'm adding how the customization looks for a NetBeans RCP module; you just need to add this target to your script:
<target name="-javadoc-with-packages" depends="build-init,-javadoc-init,netbeans" if="module.javadoc.packages">
<mkdir dir="${netbeans.javadoc.dir}/${code.name.base.dashes}"/>
<javadoc destdir="${netbeans.javadoc.dir}/${code.name.base.dashes}"
packagenames="${module.javadoc.packages}"
source="${javac.source}"
windowtitle="${javadoc.title}"
failonerror="false"
encoding="UTF-8">
<classpath refid="cp"/>
<sourcepath location="${src.dir}"/>
<doctitle>${javadoc.title}</doctitle>
<header>${javadoc.header}</header>
<doclet name="org.umlgraph.doclet.UmlGraphDoc"
path="${tools.dir}/UmlGraph-5.1/UmlGraph.jar">
<param name="-attributes" />
<param name="-operations" />
<param name="-qualify" />
<param name="-types" />
<param name="-visibility" />
<param name="-inferdep" />
<param name="-inferrel" />
<param name="-inferdepinpackage" />
</doclet>
</javadoc>
<apply executable="dot" dest="." parallel="false">
<arg value="-Tpng"/>
<arg value="-o"/>
<targetfile/>
<srcfile/>
<fileset dir="." includes="*.dot"/>
<mapper type="glob" from="*.dot" to="*.png"/>
</apply>
</target>
at this point, launching ant javadoc as usual will do the job, as the described target will just replace the one in the NetBeans RCP harness.
You can find a diagram example in context in the blueMarine javadocs and an inline example below. I'm pretty pleased with it, I just need to understand how to improve the layout - my packages have just a few classes (as it should be) and usually a few methods, but some get large boxes because of the signature of some method; also in some cases UmlGraphDoc includes in my diagram the whole description of some common classes such as String, but this is just something I can work on later. Much better than doing it by hand. BTW, Geertjan said that he will talk also about how to automatically generate a dependency diagram of the various modules in a NetBeans RCP application; also because, as Meera explained, you can put this stuff into Hudson and have the documentation automatically generate and published. Always up to date!

Opinions expressed by DZone contributors are their own.
Comments