javadoc cannot link to old docs (with old style anchors)

From Roman Marchenko



Let’s say, there is a library is being developed for further use with another Java8 project. The library development is performed using Java17 because of some legacy reasons. And these are the reasons of the developers have no option to choose another version of Java. The library is compiled with ‘-source 8’ or ‘--release 8’ options passed to both javac and javadoc (linking with Oracle’s Java8 docs with ‘-link’ option). As the result, the generated docs are not compatible with Oracle’s Java8 docs because of different forms of anchors and element IDs.

 

Even if there is a solution to additionally process external links to docs.oracle.com fixing anchors, the generated docs are still not compatible with any other documentation generated with Java8, local or external.

 

Of course, there are possible workarounds for the scenario above, however this example scenario shows that javac has backward compatibility to lower versions, but javadoc has not.