Brugge Blog

If there’s one thing that programmers dislike more than writing documentation of their code, it’s creating diagrams of their code. For Java developers, the Javadoc tool was a huge step forward, letting you create up-to-date browsable documentation in a heartbeat. Now you can do the same thing with UML thanks to the good folks who have put together the open-source UMLGraph tool.

The tool isn’t new, but the latest 4.4 release adds a significant enhancement: the ability to insert class diagrams into your Javadoc, with no extra work on your part. Wow. I have spent plenty of time over the past few years looking for and working with UML-generating tools to maintain documentation on some reasonably sized projects (100k - 300k lines of code), and this is as good as it gets in the open-source world.

So what do you do? Put a Javadoc task in your Ant build file and add a couple of parameters, then run it. Look at the output and tweak parameters to your heart’s content. Here’s a starting task skeleton

<target name="umlgraph-doc"
        description="Create integrated Javadoc and class diagrams">
    <javadoc
                classpathref="tool.classpath"
                verbose="false"
                >
        <doclet name="gr.spinellis.umlgraph.doclet.UmlGraphDoc"
                path="${tool.home}/UmlGraph.jar"
                >
            <param name="-d" value="${outputdir}"/>
            <param name="-private"/>
            <param name="-all"/>
            <param name="-inferrel"/>
            <param name="-qualify"/>
            <param name="-postfixpackage"/>
            <param name="-useimports"/>
            <param name="-collpackages" value="java.util.*"/>
            <param name="-hide" value="java.lang.String"/>
            <param name="-link" value="http://java.sun.com/j2se/1.5/docs/api"/>
        </doclet>
        <packageset dir="${src.dir}" defaultexcludes="yes"/>
    </javadoc>
</target>

What do you get?

• Package-level class diagrams inserted in your package-level documentation. Great for seeing relationships within a package.
• Class diagrams for each class, that contain the particular class, highlighted, and other classes that it is directly related to by inheritance or association. Great for seeing the universe as a particular class sees it.

Creating good diagrams is at least as hard as writing good text, so once your diagrams get above a certain size the “generated” nature of them may start to show. The language of UML may be simpler than something like English, but it is also a language where there is little teaching of style, so that there is precious little guidance on how to use it effectively. All that being said, the diagrams created by UMLGraph are very good, generally laying out inheritance in an above/below format, and associations either to the sides or below. Having a number of small diagrams also helps avoid the non-sensical “get it all on one page no matter what” diagrams that don’t say much.

So if you have a Java project with a script for creating Javadoc, slip this in for an added boost, and wait to hear what the rest of the team, or your manager, says.