Javadocs – Add Some UML Spice

Originally, this post was going to be my first one, as I was actually tackling Javadocs and UML generation together for the first time. However, after eventually completing the Javadocs and UML generation, there was way too much I had to share, hence why there are now two posts instead of one.

So to carry on from my last post, this will hopefully help you configure and set up your project to generate UML diagrams inside your Javadocs. I initially thought that this was going to be at most, a one day job, and as Murphy’s Law would have it, three days later, and I finally reached the light at the end of the tunnel!

As with the last post, I have also attached a sample project at the end of this post, so you can get a feel for how everything is configured, and what will generate. I would advise to have the sample open side by side with the post while you’re reading, to make it easier to refer to sections of code/configuration.

Because you’ve already read my last post(you have read it right?), then you’re already familiar with the @should and @sap.dependency tags and how to set them up. I’ll now describe how to go about getting the UML diagrams incorporated into your java docs.

  1. Firstly, install GraphViz. You need this little gem to generate .dot files which are essentially your mapping image, and UMLGraph will convert it into an image to be embedded into your java doc pages.
  2. Make sure that the bin folder of GraphViz is available on your PATH
  3. When editing the POM.xml (of the builder project), I added the org.umlgraph under the <pluginManagement/> element. Putting it here tells maven essentially to configure the plug-in for you, but not run it. Because this isn’t strictly a plug-in, putting it in the <build><plugins/></build> element will cause the build to fail, because it cannot find a plug-in descriptor for the declared plug-in. Trust me on this one – I only found this out when I tried running the build on our Linux build server. For some strange reason, I never got any warning like that on my Windows development machine.
  4. Next, I decided to leave the maven-javadoc-plugin inside the <pluginManagement/> element. I found this gave me the least amount of headaches, because moving it to the <builds> or <reporting> always seemed to get in the way of the build when I was messing around with how to configure the plug-ins.
  5. Don’t be tempted to try and roll the two configurations up into one. i.e. don’t try and put the configuration for the org.umlgraph into the maven-javadoc-plugin, like you might see on so many websites. It won’t work – well it didn’t work for me at least. You’ll more than likely get one of the following errors:
    • Exit code: 1 – javadoc: error – invalid flag: -author
    • Exit code: 1 – javadoc: error – invalid flag: -charset
    • Exit code: 1 – javadoc: error – invalid flag: -bottom

      • These errors have to do with the fact that javadoc is already being passed it’s own command line arguments, and its getting confused with the command line arguments being passed into the org.umlgraph

      Edit: I stand corrected here. After some tweaking, I found that you can and should roll the org.umlgraph configuration into the <configuration> element for maven-javadoc-plugin, but this will only yield successful results when the maven-javadoc-plugin is declared under the <pluginManagement> section.

  6. Make sure that you have the correct GAV. They should be the following for the UMLGraph section.
    1. <groupId>org.umlgraph</groupId>
    2. <artifactId>doclet</artifactId>
    3. <version>5.1</version>

      4. This caught me out big time! This is where reading the UmlGraph release notes proves to be incredibly valuable. As of version 5.0, it seems as though the developers of UmlGraph have changed the namespace of their package from gr.spinellis to org.umlgraph. Watch out for this, as it’ll leave you wondering why Maven is pulling down the wrong version of the plugin!

  7. Now that we have the relevant plug-ins declared in the <pluginManagement/> element, we need to define the report section. One thing to take note here, is that the <reporting/> section is mainly for generating content at the “site” goal. Because we have already defined the maven-javadoc-plugin plugin, all we have to do is declare the <reportSets> section as you’ll see in the attached example code that follows at the end of this post.
You’ll notice that the <reportSets/> section, is used to declare that you only want this plugin to execute at the “aggregate” goal. Javadoc, used to support a <aggregate>true</aggregate> element which used to be defined within the plugin definition, but that has since been deprecated and is now targeted with a javadoc goal, i.e. – javadoc:aggregate

So, the last thing to do now is run: mvn clean install javadoc:aggregate and your generated javadoc site output should look a little like this:


That now concludes how to set-up Javadocs, Custom Taglets, Stylesheets, and UML documentation generation. There is a lot more you can do with UMLGraph, and I’ll leave you with a link to their documentation. You’ll notice I have put some of their additional arguments into the example, listed in the <pluginManagement/> section under the <additionalparam/> element.

Hopefully this has been helpful in getting that UML into your Java docs site.

by | October 5, 2010 (No comments)
Java

Leave a Reply

«
»