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
