Assume javadoc-21 form for URLs linking into the javadocs #513
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
While PL/Java's docs are meant to build (mvn site site:stage) without failure on any Java version supported for building PL/Java, there have been changes over the Javadoc versions to things like the output directory structure and the spelling of anchor names for use as URL fragment IDs. Therefore, it's necessary to pick a version of Javadoc to be used when generating the docs if such things as links from the Markdown documents into the generated javadocs are to work right. Links from the generated javadocs to Oracle's published JDK javadocs are made to the Java 12 pages as a practical compromise: PL/Java 1.6.x is built for compatibility back to Java 9, but Oracle's published pages for Java 12 are the earliest to have the organization expected by a modern Javadoc. The PL/Java examples (non-modular code) have Javadoc links back to the PL/Java API (modular code), which Javadoc before 15 doesn't know how to do. Later Javadoc versions have some further aesthetic improvements. For now, assume that Javadoc 21 (the recent LTS version) will be used for generating the site javadocs, and adjust the URLs that point into the javadocs accordingly.
A slightly Orwellian feeling is probably no important reason not to also fix links in releasenotes-pre1_6 so they aren't broken when the docs are built with a present-day javadoc. There will still be unavoidable breakage given that anchor names for functions are generated by recent Javadoc versions to include parentheses, which are sanitized out of links by Velocity's Markdown processor.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
While PL/Java's docs are meant to build (
mvn site site:stage) without failure on any Java version supported for building PL/Java, there have been changes over the Javadoc versions to things like the output directory structure and the spelling of anchor names for use as URL fragment IDs. Therefore, it's necessary to pick a version of Javadoc to be used when generating the docs if such things as links from the Markdown documents into the generated javadocs are to work right.Links from the generated javadocs to Oracle's published JDK javadocs are made to the Java 12 pages as a practical compromise: PL/Java 1.6.x is built for compatibility back to Java 9, but Oracle's published pages for Java 12 are the earliest to have the organization expected for a modern Javadoc tool to link into them.
The PL/Java examples (non-modular code) have Javadoc links back to the PL/Java API (modular code), which Javadoc before 15 doesn't know how to do. Later Javadoc versions have some further aesthetic improvements.
For now, assume that Javadoc 21 (the recent LTS version) will be the version used for generating the site javadocs, and adjust the URLs that point into the javadocs accordingly.