On Mon, 10 May 2021 19:57:41 GMT, Pavel Rappo <pra...@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
