RFR: JDK-8306980: Generated docs should contain correct Legal Documents [v2]

[Mandy Chung]

On Thu, 26 Oct 2023 17:53:12 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review an update to the way that `javadoc` handles the default legal notices when generating docs.
>> 
>> Previously, the default notices were taken from the module's `legal` directory (`$JAVA_HOME/legal/jdk.javadoc`), but in some contexts, these files were either symbolic links, or "descriptive links" -- text files containing the words "Please see ..." -- on platforms that did not support symbolic links. This was set up when using `jlink` to create the image.  These "descriptive links" were insufficient and inappropriate when used in a generated docs bundle.
>> 
>> The solution is to put a copy of the necessary files into the `jdk.javadoc` module itself, at build time, as resource files, and to copy the files from there instead of the module's `legal` directory. 
>> 
>> The set of files may vary depending on the kind of build, so care is taken to not hardwire any specific list of names into the code. This means using direct access to the underlying `jrt:` file system in order to determine the set of legal notices that were set up at build time. 
>> 
>> The main test for legal notices is updated to verify that the words "Please see ..." do not appear in any of the legal notices in a generated docs bundle. There should be no other change to the set of legal notices.
>> 
>> Two other tests were affected, because they provided their own minimal file manager for use with `javadoc`, which relied on default methods in the file manager API. These default methods are not sufficiently for handling paths in non-default file systems, such as the `jrt:` file system used to access the resources for the legal notices. The fix is just to override the necessary methods.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Address review feedback

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java line 347:

> 345:             case "", "default" -> {
> 346:                 // use a dummy resource as a stand-in, because we cannot get the URL for a resources directory
> 347:                 var url = HtmlDoclet.class.getResource(DocPaths.RESOURCES.resolve(DocPaths.STYLESHEET).getPath());

Have you considered getting the legal notices directory from the parent of `resources/legal/jquery.md` instead of `resources/stylesheet.css`?   Using a relevant file would help the reader.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/16370#discussion_r1376833446