javadoc references source files from classpath entries and fails during compilation

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