On Thu, 26 Oct 2023 17:53:12 GMT, Jonathan Gibbons <[email protected]> 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
