[MJAVADOC-770] Allow building javadoc "the old fashioned way" after Java 8

• Type: Improvement
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Affects Version/s: 3.5.0
• Fix Version/s: 3.6.0
• Component/s: javadoc
• Assignee: Henning Schmiedehausen
• Reporter: Henning Schmiedehausen
• Created: 23/Aug/23 16:52
• Updated: 26/Nov/23 21:11
• Resolved: 06/Sep/23 20:35

Description

The current javadoc plugin switches the way it executes the javadoc command when the release / source version is 9 or better. Specifically, it starts using the module path and tries to build docs using modules.

Up until Java 8, it simply creates a class path and executed the javadoc command, creating a non-module aware set of documentation.

There are a lot of projects (mine included) that have moved past Java 8 but are not ready to go full modularization. Those projects usually ship with Automatic-Module-Name in the manifest.

The current JDK javadoc tooling does not work well with this type of project. Especially the module-source-path setting only works with projects that have module descriptors and javadoc chokes on patching a larger number of modules ("too many patched modules, use module-source-path"), making the aggregate goal non viable for these projects.

One way to deal with this is to lock the release version for javadocs to "8". However, once the source code moves past Java 8, the javadoc tool starts throwing warnings (e.g. 'as of release 10, 'var' is a restricted type name and cannot be used for type declarations or as the element type of an array').

The solution is actually simple: Allow a project to specify "the old way" of creating javadocs using a classpath. I have verified this by building javadocs using the "8" release version in debug mode, then manually changing the release settings in the options file to "11" and running the javadoc.sh command. This builds the javadocs as expected (java 11 syntax but non-module javadocs).

However, currently the switch between that style and "the new way" is attached to release/source and can not be controlled independently.

I propose adding a new switch to the javadoc plugin (e.g. <legacyMode>, as this is called "legacy mode" in JEP 261) with a default to "false". Setting this switch overrides the selection per release/source.

Issue Links

• fixes: MJAVADOC-701 javadoc site is broken for projects that contain modules
• is depended upon by: MJAVADOC-707 Plugin won't work if Automatic-Module-Name is used