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

[Jonathan Gibbons]

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
>>
>>