[External] : Re: JDK 17 EA build 26 - javadoc tool now writes message to STDERR instead of STDOUT?

[Jonathan Gibbons]

Jaikiran,

Both javac and javadoc provide various entry points. Some of those entry 
points take a single stream that is used for all output. You may find 
those helpful.

-- Jon

On 6/15/21 9:07 AM, Jaikiran Pai wrote:
> Thank you for these details, Jon. I'll bring this up for discussion on 
> our Ant dev list to decide how we deal with this change to take into 
> account various JDK versions and difference in their behaviour.
>
> Thank you also for creating that JBS issue to address the part where 
> some diagnostic messages are still ending up in STDOUT.
>
> -Jaikiran
>
> On 15/06/21 8:11 pm, 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://urldefense.com/v3/__https://en.wikipedia.org/wiki/Standard_streams__;!!GqivPVa7Brio!IDCS8t1LzsWEUK5PutT48IIehxxhhuuBPoUejOQ5chac2rS8qEJ2pvtvhkz5tFqOjqXtlw$ 
>>
>> -- 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://urldefense.com/v3/__https://jdk.java.net/17/__;!!GqivPVa7Brio!IDCS8t1LzsWEUK5PutT48IIehxxhhuuBPoUejOQ5chac2rS8qEJ2pvtvhkz5tFoPOSiZYg$ 
>>>
>>> -Jaikiran
>>>
>>>