yWorks yEd & UML Doclet

The core products of yWorks are the yFiles libraries for Java, .NET, and JavaScript which handle graph analysis, layout, and visualization. The libraries are enterprise-priced (thousands of dollars) but yWorks also offers some very interesting free tools. Aside from the yGuard bytecode obfuscator, these are all diagramming applications based on yFiles.

yEd Graph Editor

The yEd Graph Editor (written in Java) is a straightforward editor for technical diagrams, with special support for connected graphs. The shape palettes aren’t as complete or pretty as in big commercial products, but the user interface is pleasantly intuitive. Horizontal and vertical alignments are conveniently highlighted while dragging around objects and connections. A broad variety of layout algorithms can rearrange entire collections of nodes, rerouting their connections as desired.

Moreover, the range of supported file formats is remarkable. yEd natively saves to GraphML, allowing easy interaction with other tools. Supported export formats include not only the usual image formats but also SVG, Adobe Flash, PostScript, and PDF. The latter is especially nice for print-quality documents where images usually look like a blurry mess. yEd can import data from Microsoft Excel and even genealogy databases, although I haven’t tried that.

yWorks UML Doclet

The yWorks UML Doclet is a nifty Javadoc extension based on yFiles that creates UML diagrams from your project’s classes and inserts them directly into the corresponding Javadoc pages. The process is configurable and completely automated. The free version used to be a limited demo but is now fully functional, requiring only that a yWorks link at the bottom of each diagram is left intact.

Below is a sample diagram produced by the yWorks UML Doclet 3.0_02 for the upcoming Java version of Star Chess. I shortened the HTML a bit compared to the original version which references the Adobe SVG Viewer plugin for compatibility with older browsers. The Javadoc page also allows clicking on all identifiers to reach their corresponding pages. As you can see, the mandatory yWorks link is really quite unobtrusive.

(Note: You might not see the diagram above if you’re using an RSS reader or an outdated web browser. Try showing the post in a new window of a current browser.)

The doclet comes with fairly comprehensive documentation but some important things are easy to miss and stumped me for a while. First, generating the diagram as shown required the following changes to the configuration file, resources/ydoc.cfg:

• Change the values of all style properties from original-style.xml to the prettier yFiles-style.xml. Note that you must do this four times, as the style is specified independently for each configured diagram type!
• Uncomment the sample exclude group and changed all four nested property values to java.*,javax.*. This excludes all standard library types from diagrams. You might also wish to add javafx.* and so on.
• Change the value of the fileformat property from PNG to SVG, the associated scaling property from SHRINK_TO_SIZE to ACTUAL_SIZE, and reserveMinimum to false. This shows all diagrams at 100% scale without extra borders.

Some Javadoc flags are also needed to automatically generate diagrams along with the usual documentation. In NetBeans, those are specified under “Build: Documenting” in the “Project Properties” dialog. The complete text I entered there looks like this:

-docletpath "/Binaries/uml-doclet/lib/ydoc.jar;/Source/StarChess/dist/StarChess.jar" -doclet ydoc.doclets.YStandard -resourcepath "/Binaries/uml-doclet/resources" -umlautogen

• The complete doclet path must be specified twice, followed by its JAR location in -docletpath and by its resources folder in -resourcepath.
• You must also specify the complete path to your project JAR in -docletpath. If there’s some way to enter a project-relative path I couldn’t find it.
• Finally, don’t forget -umlautogen or a similar flag! Otherwise, the doclet will run fine but won’t generate any diagrams.

2014-04-28: Sadly, the UML Doclet’s current version 3.0_02 does not work with Java SE 8. Diagram generation fails with a Java reflection error (“no such method”). yWorks support informed me that Doclet API interfaces got new methods in JDK 8, so the entire UML Doclet (as well as any other doclets for prior Java versions) needs to be updated accordingly. Such an update is planned but not scheduled at this time, so we’d better settle in for a longer wait.