JDK 17 EA build 26 - javadoc tool now writes message to STDERR instead of STDOUT?

[Jonathan Gibbons]

https://bugs.openjdk.java.net/browse/JDK-8268774

-- Jon

On 6/15/21 8:05 AM, Jonathan Gibbons wrote:
> Jaikiran,
>
> Someone noted a detail in your message, that some "chatty" logging 
> messages were still being generated to STDOUT. That is a bug that 
> needs to be addressed.
>
> -- Jon
>
> On 6/15/21 7:41 AM, Jonathan Gibbons wrote:
>> Jaikiran,
>>
>> This was an intentional change, as part of an effort to align javadoc 
>> diagnostics and use of streams with javac.
>>
>> The general policy is that STDOUT should be used when the command and 
>> options specify to generate output ... such as the command-line help 
>> generated by the `--help` option or the version info generated by 
>> `--version`.    STDERR should be used for diagnostics and other 
>> incidental "chatty" logging messages like `Generating <file>...`
>>
>> The purpose is that STDOUT may be used to pipe output to other 
>> commands and should not be "polluted" by diagnostics and logging 
>> messages. This is generally described here: 
>> https://en.wikipedia.org/wiki/Standard_streams
>>
>> -- Jon
>>
>> On 6/14/21 9:55 PM, Jaikiran Pai wrote:
>>> While testing the Apache Ant project with the latest released JDK 17 
>>> EA (build 26)[1], we have run into an unexpected test failure in our 
>>> project. The test is pretty simple. It launches the javadoc task and 
>>> passes it a Java source file which has javadoc content which is 
>>> expected to raise a warning message. Something like:
>>>
>>> package test;
>>>
>>> /**
>>>  * This is a test class.
>>>  */
>>> public class Foo {
>>>     /**
>>>      * With a test method.
>>>      * @param baz wrong parameter name should cause warning.
>>>      */
>>>     public void foo(String bar) {}
>>>
>>> }
>>>
>>> The test then expects the javadoc tool/command to print a message of 
>>> the form "1 warning" to the STDOUT of the launced javadoc process. 
>>> Of course, other log messages are also logged to that STDOUT by the 
>>> tool.
>>>
>>> In JDK version 8, 11 and even 16, this all works as expected and the 
>>> test passes. However, this latest JDK 17 EA, it fails because it 
>>> doesn't find this message on the STDOUT of the process. I looked 
>>> into this in a bit more detail and it looks like the javadoc 
>>> command/tool is now writing this message to the STDERR of the 
>>> process. Not just that, it also looks like the tool is now writing a 
>>> lot other messages to STDERR, which previously were written to STDOUT.
>>>
>>> To give you can example, if you directly run the javadoc command 
>>> from JDK 16 and JDK 17 EA build against the above trivial code, you 
>>> will see that in JDK 16, the following were logged to STDOUT:
>>>
>>> Loading source file Foo.java...
>>> Constructing Javadoc information...
>>> Building index for all the packages and classes...
>>> Standard Doclet version 16+36-2231
>>> Building tree for all the packages and classes...
>>> Generating ./test/Foo.html...
>>> Generating ./test/package-summary.html...
>>> Generating ./test/package-tree.html...
>>> Generating ./overview-tree.html...
>>> Building index for all classes...
>>> Generating ./allclasses-index.html...
>>> Generating ./allpackages-index.html...
>>> Generating ./index-all.html...
>>> Generating ./index.html...
>>> Generating ./help-doc.html...
>>> 1 error
>>> 1 warning
>>>
>>> and JDK 16 STDERR only had:
>>>
>>> Foo.java:9: error: @param name not found
>>>      * @param baz wrong parameter name should cause warning.
>>>               ^
>>> Foo.java:11: warning: no @param for bar
>>>     public void foo(String bar) {}
>>>
>>>
>>> Now in JDK 17 EA, the same command generates the following STDOUT:
>>>
>>> Loading source file Foo.java...
>>> Constructing Javadoc information...
>>>
>>> and this STDERR:
>>>
>>> Building index for all the packages and classes...
>>> Standard Doclet version 17-ea+26-2439
>>> Building tree for all the packages and classes...
>>> Generating ./test/Foo.html...
>>> Foo.java:9: error: @param name not found
>>>      * @param baz wrong parameter name should cause warning.
>>>               ^
>>> Foo.java:11: warning: no @param for bar
>>>     public void foo(String bar) {}
>>>                 ^
>>> Generating ./test/package-summary.html...
>>> Generating ./test/package-tree.html...
>>> Generating ./overview-tree.html...
>>> Building index for all classes...
>>> Generating ./allclasses-index.html...
>>> Generating ./allpackages-index.html...
>>> Generating ./index-all.html...
>>> Generating ./index.html...
>>> Generating ./help-doc.html...
>>> 1 error
>>> 1 warning
>>>
>>> Given the kind of content now being generated in STDERR, it looks 
>>> more like a bug than an intentional change, but I wanted to check 
>>> here first before filing a JBS issue. Is this an intentional change?
>>>
>>> [1] https://jdk.java.net/17/
>>>
>>> -Jaikiran
>>>
>>>