PlantUML Taglet
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.
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
“<” and “>” 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.
-
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
↩