Creating an @plantuml Javadoc Custom Taglet

I love PlantUML, easily create UML diagrams using a description instead of having to draw them myself.

One thing I didn't like was the need to have to install the library GraphViz¹ everywhere, where I wanted to use PlantUML.

But imagine my surprise when I found out, that I don't need to any more.

The java library Smetana², which apparently functions as a drop in replacement for GraphViz should work exactly the same. And it's already integrated in PlantUML!

Can things get any better?

So, once more, let me integrate it into my javadoc build workflow of my sample Java Project using maven.

I had the idea to create a Java Doclet for generating my javadoc, but I quickly realised I should be making a PlantUML Taglet instead. It's already been done, see [3], but I wanted something a little different. But I did get some good ideas from that site.

I wanted to inline the imagedata in the src attribute of the image tag, that seems nicer than separate png files.

I also wanted to use the Smetana by default.

I managed it and uploaded it on the github⁴.

Maven integration

Adding the custom taglet to your pom.xml in the javadoc plugin should be enough. You do need to have my custom Taglet installed in your maven .m2/repository directory though.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.6.0</version>
  <configuration>
    <taglet>org.taglet.plantuml.PlantumlTaglet</taglet>
    <!-- <tagletpath>/path/to/taglet.jar</tagletpath> -->
    <tagletArtifact>
      <groupId>org.taglet.plantuml</groupId>
      <artifactId>plantumltaglet</artifactId>
      <version>1.0</version>
    </tagletArtifact>
  </configuration>
</plugin>

The following is sufficient to run javadoc and generate the diagrams:

mvn javadoc:javadoc

Eating your own dogfood

It also serves as a good example of eating your own dog food⁵.

That's right!

I added PlantUML diagrams to the javadocs of my new PlantUML Taglet, and generated the javadoc+diagrams using my PlantUML Taglet!

/**
 * Created PlantUML Diagrams based on a plantuml description.
 * @plantuml
 * PlantumlImageDataFactory : +getImageData(plantuml: String): String
 */
public class PlantumlImageDataFactory {

Worked like a charm!

It will look like this:

The image will be as raw data in the html source code, like so:

<section class="class-description" id="class-description">
<dl class="notes">
<dt>All Implemented Interfaces:</dt>
<dd><code><a href="https://docs.oracle.com/en/java/javase/17/docs/api/jdk.javadoc/jdk/javadoc/doclet/Taglet.html" title="class or interface in jdk.javadoc.doclet" class="external-link">Taglet</a></code></dd>
</dl>
<hr>
<div class="type-signature"><span class="modifiers">public class </span><span class="element-name type-name-label">PlantumlTaglet</span>
<span class="extends-implements">extends <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a>
implements <a href="https://docs.oracle.com/en/java/javase/17/docs/api/jdk.javadoc/jdk/javadoc/doclet/Taglet.html" title="class or interface in jdk.javadoc.doclet" class="external-link">Taglet</a></span></div>
<div class="block">A Taglet made by me to convert appropriate Plantuml codes into generated diagrams. Uses layout smetana instead
 of GraphViz.</div>
<dl class="notes">
<dt>See Also:</dt>
<dd>
<ul class="tag-list">
<li><a href="https://mnlipp.github.io/jdrupes-taglets/plantuml-taglet/javadoc/index.html">PlantUML Taglet</a></li>
</ul>
</dd>
<p><img alt="umldiagram" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAhMAAAC2CAIAAADsj5gHAAAAKnRFWHRjb3B5bGVmdABHZW5lcmF0ZWQgYnkgaHR0cHM6Ly9wbGFudHVtbC5jb212z..." /></p></dl>
</section>

References

[1] PlantUML - GraphViz-Dot

https://plantuml.com/graphviz-dot

[2] PlantUML - Porting GraphViz to Java

https://plantuml.com/smetana02

[3] PlantUML Taglet

https://mnlipp.github.io/jdrupes-taglets/plantuml-taglet/javadoc/index.html

[4] Github.com - PlantUML Taglet

https://github.com/maartenl/plantumltaglet

[5] Wikipedia - Eating your own dog food

https://en.wikipedia.org/wiki/Eating_your_own_dog_food