Friday, February 10, 2012

Javadocs including UML Class Diagrams with Maven and Jenkins

Project documentation is important but it is difficult to maintain it. I still have to see a team where the project documentation is maintained accurate. Did I mention that before?

It makes sense then to perform some kind of reverse engineering every so often. Javadocs (in Java projects of course) and Class diagrams can help. The first is difficult to ensure gets updated but the latter is the real implementation and so it makes sense to have it at hand when needed

A Continuous Integration server is already building your project so it makes sense for it to build the documentation as well.

  1. Install graphviz. Ubuntu for example:
    $ apt-get install graphviz
    
    OSX:
    $ brew install graphviz
    
    Windows:
    http://www.graphviz.org/pub/graphviz/stable/windows/graphviz-2.28.0.msi
    
  2. Add the below to your maven pom.xml
     <reporting>
            <plugins>
              <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>2.8.1</version>
                <configuration>
                  <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
                   <docletArtifact>
                    <groupId>org.umlgraph</groupId>
                    <artifactId>doclet</artifactId>
                    <version>5.1</version>
                  </docletArtifact>
                  <show>private</show>
                  <additionalparam>-all -constructors</additionalparam>
                  <useStandardDocletOptions>false</useStandardDocletOptions>
                </configuration>
              </plugin>
            </plugins>
     </reporting>
    
  3. Run the below to generate the local site
    $ mvn site
    
  4. Navigate the javadocs from target/site/apidocs/index.html and confirm a class shows up like below meaning a UML class diagram is added to the javadoc page
  5. Now of course you should create a project in your CI (for example Jenkins) so the javadocs get created everytime the project gets built. You better run this as a separated project just because it does take time and resources you do not want to spent when building the real project. In Jenkins you would access the site from a url like: http://jenkinsserver/myproject-documentation/site

2 comments:

Kenyatta Clark said...

Thanks for the post, but I think some of the tags should uppercased.

Nestor Urquiza said...

@ Kenyatta Clark
Thanks for the heads up. I have corrected that now. In blogspot unfortunately we cannot post literal XMLs because they get lowered case. In other words it must be escaped before, which I just did.
Best,
-Nestor

Followers