Uploaded image for project: 'Maven Javadoc Plugin'
  1. Maven Javadoc Plugin
  2. MJAVADOC-770

Allow building javadoc "the old fashioned way" after Java 8

    XMLWordPrintableJSON

Details

    • Improvement
    • Status: Closed
    • Major
    • Resolution: Fixed
    • 3.5.0
    • 3.6.0
    • javadoc
    • None

    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.

      Attachments

        Issue Links

          Activity

            People

              henning Henning Schmiedehausen
              henning Henning Schmiedehausen
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: