Bug 63438

Summary: javadoc-target fails when any OPTIONAL dependencies are missing
Product: Ant Reporter: Mikhail T. <mi+apache>
Component: Build ProcessAssignee: Ant Notifications List <notifications>
Status: NEW ---    
Severity: normal    
Priority: P2    
Version: 1.10.6   
Target Milestone: ---   
Hardware: All   
OS: All   
Attachments: Build log - with javadocs enabled

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