Generate Byte Buddy Javadoc using newer JDK

[Marcono1234]

Problems

The Byte Buddy Javadoc seems to be currently generated using JDK 8. The user experience of that Javadoc is not that great, especially for Byte Buddy which has a large amount of classes and the Javadoc missing a search feature.

Additionally Byte Buddy currently links to the JDK 5 Javadoc (e.g. for references to java.util.Collection in Byte Buddy's Javadoc). While this might be technically correct because Byte Buddy still supports Java 5, I assume the majority of users are using newer Java versions, so linking to a newer JDK version would be useful.

Feature request

It would be great if Byte Buddy

• could generate its Javadoc using a newer JDK, ideally >= 23 to benefit among others from Javadoc Search (JDK-8044243, since JDK 9) and Table Of Contents (JDK-8320458)
• link to newer JDK documentation, e.g. JDK 11, 17 or 21

Potential issues

Maybe JDK 8 is currently needed for release builds? Though maybe Maven Toolchains could be used to select a newer JDK for the Javadoc generation? actions/setup-java seems to support setting up Maven Toolchains.

[raphw]

The problem is that JDK 8 is the newest JDK that supports Java 5 as a target. As of now, I still want to support it, and thus I am bound by Java 8.

[Marcono1234]

The problem is that JDK 8 is the newest JDK that supports Java 5 as a target.

As long as the source code is also valid for Java 8 or newer, that should not be a problem I think. The source / target version could just be changed for the Javadoc plugin, I think that should not matter for the result. For everything else it could keep using Java 5.

---

I have created an incomplete proof-of-concept here: https://github.com/Marcono1234/byte-buddy/tree/javadoc-poc And corresponding action run here: https://github.com/Marcono1234/byte-buddy/actions/runs/15197102262 (see also "Artifacts" at the bottom of the page containing the generated Javadoc)

A few notes:

• The proof-of-concept uses a separate workflow to demonstrate the behavior, and uploads the Javadoc just for demonstration purposes. I think this change could be integrated into the release job of the existing main.yml workflow by just including 23 as additional java-version there, without any additional workflow changes. As mentioned above actions/setup-java will take care of adjusting the Maven Toolchain configuration.

• I have temporarily set <failOnWarnings>false</failOnWarnings> because the newer JDK reports some new warnings, it seems they are mainly about implicit default constructors without documentation comment

• I have also changed it to link against the Java 11 API, though this causes a new warning:

  The code being documented uses packages in the unnamed module, but the packages defined in https://docs.oracle.com/en/java/javase/11/docs/api/ are in named modules.

  It seems the javadoc tool has --link-modularity-mismatch which might help to reduce this from a warning to an info message?

• This setup might also require a JDK 23 and corresponding Maven Toolchain configuration when building Javadoc locally[^1], but only then

• I have only had a short look at the generated documentation and it looked ok to me, maybe I have overlooked any issues with it though

What do you think?

[^1]: Though it seems Maven executes the plugin even if it cannot find a matching toolchain?

[raphw]

I thought about this, but I think the toolchain will become even more complex for rather little benefit. Most people consume Javadoc while coding through an IDE. And if the javadoc is really important, it can easily be produced with a modern JVM locally.

Thanks for your thoughts and suggestions, though! I appreciate the interesting idea you brought forward.