RFR: JDK-8267204: Expose access to underlying streams in DocletEnvironment

[Jonathan Gibbons]

On Tue, 18 May 2021 11:39:45 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> I have two high-level questions: (1) Why would Doclet API expose standard streams given that it already has `jdk.javadoc.doclet.Reporter`? (2) Is `PrintStream` the most appropriate abstraction for a standard stream? (For example, the `javax.tools.Tool` API uses `OutputStream` for that purpose.)

1. Reporter says nothing about streams.  javadoc is inconsistent with javac and when run with two streams, it sends warnings and errors to one stream and notes to the other.  javac now sends all diagnostics to the error stream, leaving stdout for command-line help etc.   This PR is part 1 of 2; having made both streams explicitly available here, part 2 will align javadoc with javac.   Also, DocletEnvironment seemed a more appropriate place to expose the streams.

2. For passing in streams/writers, higher level types, like OutputStream and Writer, are OK, because they can be wrapped into the more convenient forms. For passing out streams/writers, you want to pass out the Print--- forms, to save the user having to wrap and flush and close them.

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

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