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

[Jonathan Gibbons]

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