Bug 63438 - javadoc-target fails when any OPTIONAL dependencies are missing
Summary: javadoc-target fails when any OPTIONAL dependencies are missing
Alias: None
Product: Ant
Classification: Unclassified
Component: Build Process (show other bugs)
Version: 1.10.2
Hardware: All All
: P4 regression (vote)
Target Milestone: 1.10.8
Assignee: Ant Notifications List
Depends on:
Reported: 2019-05-15 14:09 UTC by Mikhail T.
Modified: 2020-01-10 13:43 UTC (History)
0 users

Build log - with javadocs enabled (45.92 KB, text/plain)
2019-05-15 14:09 UTC, Mikhail T.

Note You need to log in before you can comment on or make changes to this bug.
Description Mikhail T. 2019-05-15 14:09:55 UTC
Created attachment 36587 [details]
Build log - with javadocs enabled

Although building the actual JARs works -- skipping the pieces requiring the optional dependencies (like bcel, log4j, xerces, etcætera), the "javadocs" target fails if any of these options aren't available at build-time.

The work-around is to change "failonerror" attribute from "true" to "false" -- but the proper fix would exclude the same parts, that the JARs-creation excluded.

Attached is the log of my attempts to build Ant from source on a FreeBSD system -- I'd appreciate a patch to build.xml... Thank you!
Comment 1 Jaikiran Pai 2019-05-16 12:39:59 UTC
I was able to reproduce this. The javadoc tool seems to error out and exit with a non-zero exit code when it cannot resolve a "reference". You can, in fact, find 26 "reference not found" errors which match with the final "26 errors" summary message in that log you attached. These references are mostly of the form @throws JSchException, @see and such. It's understandable why those references aren't found.

However, I'm unsure why the javadoc tools errors out in such cases and thus contradicting with what it says on it's documentation page[1] for Java 1.8 (the version you are using):

"Reports warnings for bad references...


Messages may be either warnings or errors, depending on their severity
and the likelihood to cause an error if the generated documentation were
run through a validator. For example, bad references or missing Javadoc
comments do not cause the javadoc command to generate invalid HTML, so
these issues are reported as warnings."

I've asked for clarification about this on the openjdk javadoc-dev mailing list and will decide how we can proceed with this one, once we get clarity on the matter.

[1] https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#CHDCIBFC
Comment 2 Mikhail T. 2019-05-16 14:10:52 UTC
(In reply to Jaikiran Pai from comment #1)
> However, I'm unsure why the javadoc tools errors out in such cases

It errors out because of the explicit "failonerror=true" in the <javadoc> element :)

The quick-dirty workaround is to simply flip the above setting to false -- as I'm already doing in my update to FreeBSD port devel/apache-ant (see https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=237913)

The proper fix, I guess, is to painstakingly exclude the sources dependent on the missing optional dependencies from Javadoc as they are already excluded from compilation...

Then the failonerror can be proudly set back to true again...
Comment 3 Jaikiran Pai 2019-05-16 14:31:01 UTC
What I meant in my previous reply was that, based on the documentation of the javadoc tool shipped in the JDK (the one which we use in that task), I don't expect that tool to fail with an error in first place for such references and thus the failonerror attribute of that task shouldn't play a role.

I agree ultimately this might (and probably will) need a change to our build.xml file to either allow configuring the failonerror value for this target or make some kind of path exclusions or maybe even pass along a -Xdoclint option to that task to use something like "-Xdoclint:all,-reference". But beforing getting to any of that, I personally am interested in understanding why the JDK shipped javadoc tool is failing in first place.
Comment 4 Mikhail T. 2019-05-16 15:30:27 UTC
(In reply to Jaikiran Pai from comment #3)
> But before getting to any of that

Let's implement the fixes in parallel with -- rather than after -- figuring out, why JDK is the way it is...
Comment 5 Jaikiran Pai 2019-05-21 05:08:31 UTC
This has now been acknowledged[1] as a bug in the JDK's javadoc tool itself and is being tracked in the JDK bug tracker at [2].

[1] https://mail.openjdk.java.net/pipermail/javadoc-dev/2019-May/001068.html
[2] https://bugs.openjdk.java.net/browse/JDK-8224266
Comment 6 Alexander Grund 2020-01-10 12:42:17 UTC
https://bugs.openjdk.java.net/browse/JDK-8224266 has come to a resolution that this is NOT a bug in javadoc but intended and specified behavior.

The issue in ant surfaced in 1.10.2 due to the removal of the `withDoclint` parameter and hence not passing `additionalparam="-Xdoclint:none"` to the javadoc target. Hence a fix is to revert that change and build without doclint by default.

See also https://stackoverflow.com/questions/56750209/how-to-successfully-build-ant-source-code/59681717#59681717
Comment 7 Jaikiran Pai 2020-01-10 13:43:19 UTC
Hello Alexander, thank you very much for the detail about the change that caused this regression. I hadn't previously looked at our build.xml history to figure this out. Thanks to your input, I've now undone that change and pushed a commit to master branch upstream and credited you for this fix.