Nice Javadoc and UML diagrams with Maven

Geek & Poke published an appropriate strip recently. Any coder will consider the documentation writing a hassle. Yet, they will also be first in line to regret the absence of up-to-date explanation.

Well maybe not them, since people like me rather read code than documentation, but then bosses will be. I was recently asked if we had UML diagrams of our project. Of course not, but automatically generated diagrams should do the trick, isn’t it?

I was answered that finding a free-to-use tool was near impossible. “Challenge accepted!

As it turns out, I ended up with a nice Javadoc, including diagrams for both classes and packages (the one of the root of the project is quite impressive, by the way). Here is a quick preview.

In this post, I will detail how I proceeded to get this result.

Step one: Generating Javadoc with Maven

That part is nothing complicated. Just a simple use of Apache’s Maven Javadoc plugin. Assuming you have a multi-module project as I do (and it is even easier with a single module), you just have to add this declaration in your main pom.xml file:

See the plugin’s website for more information about the configuration options. In my own case, I want to show all elements, including private elements.

Moreover, I previously tried to make the doclava doclet work with my configuration, but some doclets seem not to work properly with Maven projects and transitive dependencies. I however kept some parts of the configuration, which in the end looked like the following.

Once your POM is set, you can call this section by using the proper Maven goal. javadoc:aggregate will generate full Javadoc, including all the classes of all sub-modules, while javadoc:javadoc will only process the current module.

Please remember that your classes must have been compiled for the Javadoc to be generated.

Step two: Applying a stylesheet to Javadoc

I used JBoss.org stylesheets for Javadoc. They are available for download right here.

After having included them in your project, you just have to update your POM configuration in the following way.

You van run your new favorite Maven goal. The resulting site should now be less agressive to your eyes.

 Step three: Including UML diagrams in the Javadoc

The real challenge. I first found something about using UMLGraph, but it had two main drawbacks:

  • it required the use of GraphViz, making the Javadoc generation platform-dependent, since GraphViz has to be installed on the compiling machine;
  • it has the same problem as doclava related to transitive dependencies and fails generating the documentation on my project.

Therefore I searched for another solution and found yWorks’ UML doclet. I downloaded the Community edition and adapted my project.

First, you must include the downloaded resource into your project. Then, I suggest you set a property defining the emplacement of this in your project.

Then, you must adapt the Javadoc plugin configuration.

Now, as I think the dotnet style better integrates with JBoss.org’s stylesheets, I encourage you to modify the ydoc.cfg file, setting the following attribute to the proper value.

You should be good to go. Always the same good ol’ goal, the plugin configuration will take care of the rest.

Still better: include yWorks in a repository

Worst weakness in this system: yWorks never committed their community version to a Maven repository, and you have to version it along your project. I consider versioning binaries a bad practice when it can be avoided.

And you can avoid it! Well, if you have your own repository, that is. A Nexus, for instance, perhaps used as a proxy to other Maven central and others. In this case, you can (and probably already have) define a third-party repository for the precise case of dependencies normally not available via Maven.

Then, you will be able to create an artifact in your Nexus. You will have to upload the ydoc.jar and adapt your POM accordingly.

And you can now remove the doc and lib directories you previously added to your project and save your SVN/Mercurial/Git server from keeping track of changes to the doclet binaries.

And now, I hope you will enjoy to document your code just to see the beautiful Javadoc Maven generates for your project.

True story.

Edit: if you do not have a Nexus, you can follow yWorks’s own instruction on how to configure your project…

Published by

Cyrille Chopelet

Programming addict, UX philosopher, casual gamer, sci-fi enthusiast, hi-tech dilettante, ... Some people even call me a geek.

19 thoughts on “Nice Javadoc and UML diagrams with Maven”

  1. Nice Post, but I have one question…
    What artifact did you upload to your nexus repository, the zip file or only the ydoc.yar ?
    There is also a styleed.yar in the 3.0.02 zip
    Regards Daniel

  2. A quick follow up: I added the ydoc.jar to my nexus repository and now its working.
    Now the \${basedir} property will not work on multi-module project builds, the easiest way to get this to work is to use \${user.dir} as this points to the multi-module project root, when you start the build from the root folder.
    I mailed yworks and suggested that the resources could be looked-up from a jar (plugin-dependency) as it is suggested in checkstyle plugin doc.
    AND: styleed.jar is a stylesheet editor to create custom ydoc stylesheets…
    Cheers Daniel

    1. OK, I see I was too long. I wanted to check on our Nexus repository tomorrow before risking being wrong in answering you. Thank you for your feedback!

  3. Hi Cyril,
    First I would like to thank you for this tutorial who present an alternative to GraphViz one.
    However, I am trying since 1h to run it on my environment and I am getting a frustrating message:
    ….. some log before
    YStandard Doclet version 3.0_02
    No license file found.
    [done in 968 ms]
    [INFO] ————————————————————————
    [INFO] BUILD FAILURE
    [INFO] ————————————————————————
    [INFO] Total time: 2.597s
    [INFO] Finished at: Wed Jul 03 16:35:24 BST 2013
    [INFO] Final Memory: 15M/247M
    [INFO] ————————————————————————
    [ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.8.1:aggregate (default-cli) on project test-harness: An error has occurred in JavaDocs report generation:
    [ERROR] Exit code: 1 – java.util.MissingResourceException: Could not find xml resources. Please check your -docletpath and -resourcepath options.
    [ERROR]
    [ERROR] Command line was: C:\Java\java7\32\sdk\jre\..\bin\javadoc.exe -J-Xmx1024m @options @packages
    [ERROR]
    [ERROR] Refer to the generated Javadoc files in ‘C:\Work\target\site\apidocs’ dir.
    [ERROR] -> [Help 1]
    [ERROR]
    [ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
    [ERROR] Re-run Maven using the -X switch to enable full debug logging.
    [ERROR]
    [ERROR] For more information about the errors and possible solutions, please read the following articles:
    [ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException

    1. I sorted it out 🙂 I added the following tag
      <license>${yworks.uml.path}/resources/ydoc.license</license>
      and it is fine.
      regards,
      Karim.

  4. Hi, Cyrille – I’ve been using the ydoc doclet for a while.. at some point along the way the UML diagrams i see generated have gaps in them. I’m wondering if this is ‘by design’ to get us to move from community edition to the paid edition? Do you see gaps in the diagrams that make them look like tiles (with whitespace between them)? I’m wondering if there might even be some .css fix for this. Thanks in advance for your help – /chris

    1. Hi, Chris. I’ve used the doclet for a while too, now, and never met this problem, though I have generated some quite large graphs.

      The graphs are split into tiles, though. A practice from older Internet, to load large images quicker. It seems that for some reason, some of these tiles fail to load. Maybe you lost some of the tiles along the way, but I could not tell how or why.

  5. Thanks!
    All works fine with the UML unless some classes are ‘cut’ in the middle , so I see the left side of the box – then emptiness – and then the right side of the box.
    I am using all your stuff except the Jboss.org Stylesheets.
    Any ideas ?
    Working for a museum, we would like to use ‘good’ licenses and in the jungle of licenses – do you know what license I am dealing with here?

    regards, i

    1. OK, so Marc answered before I did for the gaps between images: the graphs are a table of images, so your CSS probably puts a cellspacing or cellpadding this table should not have, or margins around the images. Some CSS should do it.

      As for the license, no, I cannot tell you because there are no license specified on the homepage. You have two editions:

      yWorks UML Doclet is available as a free-of-charge Community Edition and a Professional Edition.

      For more details on the differences between the two, see the section yWorks UML Doclet Editions.

  6. I was experiencing the same issue, and turned out some CSS rule caused the gap (padding) between the table cells where the diagram is displayed.
    It was several months ago so I don’t remember what exactly was the problem, but looking at my fixed javadoc html, seems that the CSS class ‘UmlTableCell’ had some extra padding which I manually removed.
    I uploaded my full stylesheet to dropbox, try to use it as-is if you can’t fix the problem.
    Direct link: https://db.tt/Q9C5GSVV

    Regards, Marcell

    1. Hello.
      I found solution for the gap:

      yworks-uml-doclet-3.0_02-jdk1.5\resources\ydoc.cfg->formats.image.tiling->enabled=false

      and no gap anymore…

"Wit beyond measure is man's greatest treasure." − Rowena Ravenclaw