XML doclet

By Norm Tovey-Walsh on August 16, 2023 at 10:00a.m.

Historically, we’ve used a customized version of JELDoclet to generate XML from Javadoc. We use the XML to construct parts of our website. The Javadoc APIs used by JELDoclet (and all of the other Javadoc-to-XML doclets that I could lay my hands on) have been deprecated as of Java 9 and will eventually be removed from the JDK.

On a whim last weekend, I took a stab at simply rebuilding an XML doclet on top of the new Javadoc APIs. You can find the results of that effort in the xmldoclet repository.

It’s only version 0.1.0, but I think it’s broadly functional. It handles all of the sources I’ve thrown at it, including the Saxon Java products which are fairly large and complex. If you try it out and discover that it produces output that seems incomplete or incorrect, please open an issue.

I can’t say I’m especially fond of the Javadoc APIs. In particular, although you need to know what imports a class has in order to correctly resolve the names of types, the public APIs provide no access to that information. In the end, I applied an old maxim:

If brute force doesn’t work, you’re not applying enough brute force.

I simply included the Java parser that we use for the transpiler and parse the sources myself.

Comments most welcome…