PlantUML Taglet

A taglet that generates UML diagrams with PlantUML for inclusion in the javadoc.

Please note that starting with version 2.0.0 the taglet works with the API introduced in Java 9. It has been tested with Java-11.

Starting with version 3.0.0 the taglet requires Java-17.

Simply use the @plantUml tag to generate the graphics file from the PlantUML source1:

/**
 * Description.
 *
 * <img src="example.svg">
 *
 * This package/class ...
 *
 * 
 *
 * 
 * 
 * 
 *
 * @plantUml example.svg
 * Alice -> Bob: Authentication Request
 * Alice <-- Bob: Authentication Response
 */

This is rendered as (generated with only one usage pattern active):


Description.

Example Diagram

This package/class …


The usage of “<” or “>” in PlantUML makes javadoc complain about illegal HTML tokens when using the block tag. Of course, you could use “&lt;” and “&gt;” but this reduces the readability of the UML descriptions and is therefore not supported (the taglet does not scan for these sequences and convert them). You could globally disable HTML checks with e.g. “-Xdoclint:-html” when using PlantUML but this might prevent other problems from being detected.

The preferred approach is to use the inline tag or to put the PlantUML source in comments as shown below.

/**
 * @plantUml package.svg
 * <!--
 * Bob <-- Alice: Authentication Request
 * Alice <-- Bob: Authentication Response
 * -->
 */

The taglet removes the comment delimiters and uses the resulting content as PlantUML source. Of course, you also have to avoid all “-->” arrows in your PlantUML description as this would terminate the HTML comment prematurely. Luckily, this isn’t too hard because you can always exchange the left and right side of such a relation.

It’s also possible to use @startuml and @enduml instead of @plantUml, which is the common usage pattern. @startuml is simply a synonym for @plantUml and @enduml will be ignored entirely. Use this for compatibility with other tools, like e.g. the PlantUML Eclipse Plugin or the PlantUML IDEA Plugin.

Invoking

Gradle

Configuring a taglet in the javadoc task is not explicitly shown in the DSL Reference. The required properties can be found in the standard options

Here’s an example:

configurations {
    javadocTaglets
}

dependencies {
    // See above for the latest version.
    javadocTaglets "org.jdrupes.taglets:plantuml-taglet:<version>"
}

javadoc {

    options.tagletPath = configurations.javadocTaglets.files as List
    // List the taglets that you want to use.
    options.taglets = ["org.jdrupes.taglets.plantUml.<Taglet>", ...]
    ...
}

The latest version available on maven central is shown in the badge at the beginning of this page.

Command line

Specify the taglet on JavaDoc’s command line:

javadoc -taglet org.jdrupes.taglets.plantUml.Taglet -tagletpath /path/to/plantuml-taglet.jar:/path/to/plantuml.jar

This could be simplified by providing a “fat jar”, but I doubt that anybody would really use it.

Maven

Still using this? Well, you’re on your own…

Notes

This taglet is released under the GPL 3.0.

The project’s sources can be found on GitHub.


  1. The PlantUML source for the example above is actually in the package description instead of the overview source file. Java-11 to Java-17 drop block tags from an overview file. (Used to worked in Java-8, works again in Java-18.) See the report in the Java Bug Database

Packages
Package
Description
The main package.