Formatting JavaDoc with Asciidoctor and Java 11.

What Is Asciidoctor And Why Use It?

Asciidoctor is a plain-text formatting system, similar to Markdown. You write plain-text, with some extra symbols, in a nice an fairly intuitive way, and Asciidoctor will format it in a way that looks nice. Markdown is simpler, but Asciidoctor has a more complete set of features. These features are particularly relevant when writing documentation that spans multiple files, and include code samples and diagrams. You can of course achieve the same with Markdown through various hacks and extensions, but in Asciidoctor these things come standard, which is why it is my preferred system for writing technical documentation.

An Asciidoctor Doclet For JavaDoc.

API documentation, such as the JavaDocs for a Java library, is technical documentation. Having the full formatting and organizing power of Asciidoctor available when writing JavaDocs has proven useful. For instance, my Stormpot library formats its JavaDocs using Asciidoctor.

This is achieved using a custom doclet that extends the capabilities of the javadoc tool to format Asciidoctor. Such a doclet already exists, called Asciidoclet. However, Java 9 completely changed the internal JavaDoc APIs in incompatible ways, rendering the existing Asciidoclet unusable from Java 9 onward.

It is possible to fix Asciidoclet, using a fair number of hacks. Unfortunately Asciidoclet appear to be largely unmaintained at this point, with no release since June 2018, and issues and pull requests left unaddressed.

Using Asciidoclet Anyway.

Although there is no official Asciidoclet support for newer Java versions, we can still make it work. The “fair number of hacks” I mentioned above have already been done, and currently sit idle in a pull request. All we need to do, is to work around the lack of an official release.

Note that though I mentioned that the incompatibilities started from Java 9 onward, my fork requires at least Java 11. At this point, there are most likely no one, who is both interested in writing javadoc comments in Asciidoctor, and using either Java 9 or 10, and also cannot upgrade to Java 11.

It turns out that the JavaDoc Maven Plugin can only depend on external doclet dependencies that can be obtained through the Maven Central repository. In other words, adding a JitPack repository with my forked version does not work.

The doclet instead needs to be vendored. That is, the jar-file needs to be copied into every repository that needs it. Then the jar-file can be referenced on the doclet path directly.

First, download the asciidoclet-2.0.0-shaded.jar file from the release page of my fork. Move it to a location in your repository that makes sense for such binary dependencies, for instance a build directory. Then finally configure the JavaDoc plugin in your pom.xml file as shown in the example on the release page. The additionalJOptions part is important, because they are required in order to make some of the hacks work.

Once this is done, you will be able to write javadoc comments using the full power of Asciidoctor. Here is an example from Stormpot, my object pool library, where I use both file includes, admonitions, and other formatting tools.

Closing Thoughts.

While it is a shame that Asciidoclet does not appear to be maintained anymore, it is certainly still possible to get Asciidoctor to render our JavaDoc comments in Java 11 and onward. It is a shame that the JavaDoc APIs changed in the way they did. They require either terrible hacks to access internal APIs, or they require any custom doclet to completely reimplement all features of the standard doclet, which I think is an unreasonably tall bar to get something working. The hacks are in place now, however and will continue to work until the JavaDoc internals change further. I don’t know what the plans are for that, but we are at least safe on Java 11 for the time being. Long term, a standard doclet reimplementation may well be required, but I prefer to punt that for as long as possible. Alternatively we could also hope that the standard doclet implementation get opened up for extension, eliminating the need for many or all of the hacks currently required. Whatever the case, I hope to keep this doclet working for as long as possible. I still prefer writing my JavaDocs in Asciidoctor.