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
