RFR: JDK-8259530: Generated docs contain MIT/GPL-licenced works without reproducing the licence

[Jonathan Gibbons]

On Mon, 10 May 2021 19:57:41 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Please review a change for JavaDoc, for the Standard Doclet to copy legal header files into the generated docs from a default or designated directory.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java line 361:
> 
>> 359:                     try (OutputStream out = df.openOutputStream()) {
>> 360:                         Files.copy(entry, out);
>> 361:                     }
> 
> I'm surprised to see you using `Files.copy(Path source, OutputStream out)` instead of `DocFile.copyFile(DocFile)`.
> 
> Last time I suggested we use Files.copy instead of the DocFile.copyFile in jdk.javadoc, you argued that the latter is more helpful to an end-user:
> 
>> In terms of general philosophy, when any IO problem occurs, I think it is important to specify the file involved, to give the end-user the best information for that person to diagnose the external condition. To me, that is better and more specific than saying "error copying from A to B, something went wrong with one of them".

Yeah, good call.
It required some tweaks to `DocFile` and `DocFileFactory` to make it happen, but it's a move in the right direction.

`DocFileFactory` used to be new and clever and encapsulated the different kinds of file system. Now, NIO is accepted and standard. I would still keep `DocFile` to encapsulate `Path` vs. `FileObject`, but there is potential cleanup to improve this part of the code, and (most notably) convert command-line options to use `Path` instead of `String` where that is appropriate.  But that is a different PR.

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

PR: https://git.openjdk.java.net/jdk/pull/3954