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

[Jonathan Gibbons]

On Wed, 25 Oct 2023 23:38:38 GMT, Erik Joelsson <erikj 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.
>
> make/modules/jdk.javadoc/Copy.gmk line 36:
> 
>> 34:     DEST := $(JDK_JAVADOC_DOCLET_RESOURCE_DIR)/legal, \
>> 35:     FILES := $(wildcard $(TOPDIR)/src/jdk.javadoc/share/legal/*.md), \
>> 36:     FLATTEN := true, \
> 
> I don't think `FLATTEN := true` should be needed here. That is only supposed to have an effect if the list of source files are located in different directories, but you want them all to end up in the same target directory. In this case since you are using wildcard, we know that all the source files are in a single directory.
> 
> Same goes for the other instance below.

Noted. Will fix.  I was just copying code from elsewhere.

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

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