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

[Jonathan Gibbons]

On Thu, 20 May 2021 16:39:39 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Please review a relatively simple update to expose the 1 or 2 streams available within javadoc for writing expected or diagnostic output.
>> 
>> The change at this time is just to _expose_ the streams; followup work may change how we _use_ them.
>> 
>> There are two points of note:
>> 
>> * `JavadocTester` is extended to provided access to the javadoc entry point used by the launcher. This is simpler than exec-ing the tool to invoke the entry point, and allows us to use the existing code to capture and analyze the output.
>> * The initialization of the default streams in `Messager` is deferred, to allow `Messager` to use the values of `System.out` and `System.err` at the time that javadoc is started, instead of when the class was loaded. This is part of the problems described separately in JDK-8267203, but which needs to be addressed here as part of this work.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java line 156:
> 
>> 154:          * The implementation provided by the `javadoc` tool to
>> 155:          * {@link Doclet#init(Locale, Reporter) initialize doclets}
>> 156:          * always returns a non-{@code null} value.
> 
> Did you mean `{@link Doclet#run(DocletEnvironment) run doclets}` instead?

Hmm, I guess I did. Good catch.

> src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java line 176:
> 
>> 174:          * The implementation provided by the `javadoc` tool to
>> 175:          * {@link Doclet#init(Locale, Reporter) initialize doclets}
>> 176:          * always returns a non-{@code null} value.
> 
> Same as two preceding comments.

Same as preceding response!

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

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