restx-apidocs-doclet compatibility with Java 11

[nhumblot]

restx-apidocs-doclet has some breaking changes when using a jdk11.

pom.xml

First issue is located in the pom.xml. The following dependency cannot be imported due to tools.jar removal:

<dependency>
    <groupId>com.sun.tools</groupId>
    <artifactId>tools</artifactId>
    <version>${java.version}</version>
    <scope>system</scope>
    <systemPath>${java.home}/../lib/tools.jar</systemPath>
<dependency>

ApidocsDoclet.java

Removing this dependency (or not having it for java11) generates one error into the module in ApidocsDoclet.java, due to the call to Standard.validOptions(options, errorReporter) at line 182. This method has been deprecated in Java 9 and removed in Java 10. The underlying class HtmlDoclet.java has been removed as well.

Its goal is to validate potential parameters passed to the javadoc command. Options for jdk8 can be found here: https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html

I couldn't find any exhaustive documentation about parameters available for the new javadoc command except from the tool itself:

Usage: javadoc [options] [packagenames] [sourcefiles] [@files]
  -overview <file>                 Read overview documentation from HTML file
  -public                          Show only public classes and members
  -protected                       Show protected/public classes and members (default)
  -package                         Show package/protected/public classes and members
  -private                         Show all classes and members
  --help                           Display command line options and exit
  -doclet <class>                  Generate output via alternate doclet
  -docletpath <path>               Specify where to find doclet class files
  --module-source-path <path>      Specify where to find input source files for multiple modules
  --upgrade-module-path <path>     Override location of upgradeable modules
  --module-path <path>, -p <path>  Specify where to find application modules
  --add-modules <module>(,<module>)*
                                   Root modules to resolve in addition to the initial modules,
                                   or all modules on the module path if <module> is ALL-MODULE-PATH.
  --limit-modules <module>(,<module>)*
                                   Limit the universe of observable modules
  --source-path <path>             Specify where to find source files
  -sourcepath <path>               Specify where to find source files
  --class-path <path>              Specify where to find user class files
  -classpath <path>                Specify where to find user class files
  -cp <path>                       Specify where to find user class files
  -exclude <pkglist>               Specify a list of packages to exclude
  -subpackages <subpkglist>        Specify subpackages to recursively load
  -breakiterator                   Compute first sentence with BreakIterator
  -bootclasspath <path>            Override location of platform class files
                                   used for non-modular releases
  --system <jdk>                   Override location of system modules used
                                   for modular releases.
  -source <release>                Provide source compatibility with specified release
  --release <release>              Provide source compatibility with specified release
  -extdirs <dirlist>               Override location of installed extensions
  -verbose                         Output messages about what Javadoc is doing
  -locale <name>                   Locale to be used, e.g. en_US or en_US_WIN
  -encoding <name>                 Source file encoding name
  -quiet                           Do not display status messages
  -J<flag>                         Pass <flag> directly to the runtime system
  -X                               Print a synopsis of nonstandard options and exit
GNU-style options may use = instead whitespace to separate the name of an option
from its value.

ApidocsDocletRunner.java

To make the javadoc command work with jdk11, we will also have to change ApidocsDocletRunner.run() method so it generates valid arguments based on the java version.

The -d parameter seems to be the only issue ? To be confirmed.

[nhumblot]

Comment from @xhanin in #318 regarding ApidocsDoclet.validOptions(String[][] options, DocErrorReporter errorReporter) removal, telling maintainer's vision on how to address this issue:

It seems that this will prevent the doclet from working with options on java 8 and java 9. As stated here: https://docs.oracle.com/javase/8/docs/jdk/api/javadoc/doclet/com/sun/javadoc/Doclet.html

This method is required by the Doclet api to accept options.

Maybe a better option would be to have a new module restx-apidocs-doclet-11 compatible with doclet api 11, and keeping this module compatible with java < 11.

The new doclet api is documented here: https://openjdk.java.net/groups/compiler/using-new-doclet.html

It has a brand new way to deal with options.