Sources read from classpath JARs cause errors during compilation

[Dawid Weiss]

Here is another gem I discovered while porting an ant build to gradle.
Applies to Java 11-14. Say you're compiling class Bat like this:

javadoc -classpath p2.jar -d tmp p3/bat/Bat.java

p2 contains class Baz which Bat imports. Baz in turn has a reference
to a class not on classpath (annotation, for example).

The runtime behavior now forks into two scenarios:

1) p2 contains just Baz.class: compilation succeeds, documentation is generated.

1) p2 contains Baz.class AND Baz.java (sources inside the archive):
javadoc fails with something like this:

Loading source file p3\bat\Bat.java...
Constructing Javadoc information...
O:\repos\lucene-gradle-master\solr\solrj\build\tmp\repro\p2.jar(/baz/Baz.java):3:
error: package bar does not exist
import bar.Bar;
          ^
O:\repos\lucene-gradle-master\solr\solrj\build\tmp\repro\p2.jar(/baz/Baz.java):5:
error: cannot find symbol
@Bar
 ^
  symbol: class Bar
2 errors

Note the error message refers to the source file from classpath (!),
not javadoc's source path.

This causes grief when you don't have control over classpath entries.
In Lucene's case it's this one:

zookeeper-jute-3.5.5.jar(/org/apache/zookeeper/data/Stat.java):23:
error: package org.apache.yetus.audience does not exist
import org.apache.yetus.audience.InterfaceAudience;
                                ^

A repro code for the above is attached to the Lucene issue at [1]
(can't send attachments from gmail).

Dawid

[1] https://issues.apache.org/jira/browse/LUCENE-9132