Testing Apache Ant against JDK 8 EA builds

[Jonathan Gibbons]

On 12/23/2013 04:40 AM, Rory O'Donnell Oracle, Dublin Ireland wrote:
> Hi Stefan,
>
> CC'ing the javadoc mailing list, best place to discuss.
>
> Rgds,Rory
> On 22/12/2013 07:22, Stefan Bodewig wrote:
>> On 2013-12-19, Rory O'Donnell Oracle, Dublin Ireland wrote:
>>
>> Some problems may have been fixed, but the user experience is not much
>> better, sorry.
>>
>> I tested b120 against Ant, Commons Compress and XMLUnit.  I didn't see
>> any test failures, that's the good news[1].  But I also wouldn't be able
>> to cut releases as javadoc finds > 100 errors for all of them.  Things
>> that are errors now that used to work before:
>>
>> * self-closing tag not allowed
>>
>>    I beg your pardon, the tool obviously recognizes them, why isn't it
>>    willing to act on a <br/> like any browser would do?

<br/> is not legal HTML, even though some browsers accept it. If you 
want to disable the checks, use -Xdoclint:none.

>>
>> * it has become pickier for uses of < > and & inside javadocs
>>
>>    This is good IMHO
>>
>> * @link and @see have changed behavior, in particular we have quite a
>>    few places with
>>
>>    @see "http://www.winzip.com/wz54.htm"
>>
>>    that used to work just fine but now creates "unexpected text" 
>> warnings
>>    - "foo" is supposed to create a "foo" non-link and nothing suggests
>>    that the content must not look like an URI.
>>
>>    Both tags ignored content they couldn't parse before.

This looks like a bug that needs to be investigated. The spec is quite 
clear that strings args should be accepted. It looks like the problem is 
more with the string arg than with the content of the string.

>>
>> * unknown @tags cause errors
>>
>>    I'm a bit torn on this.  In a way this is good to prevent typos but
>>    then again Commons Compress uses JCIP annotations to flag 
>> thread-safety
>> <http://commons.apache.org/proper/commons-compress/conventions.html>.
>>    I wouldn't want to add an external dependency to the build or create
>>    my own dummy-taglets just to keep those annotations.

Recent builds of JDK 8 should take the command line -tag option into 
account,
and so not complain about user-defined tags.

>>
>> I just spent somewhere between half an hour and an hour to get Commons
>> Compress down to just the "unknown tag" errors
>> <http://svn.apache.org/viewvc?view=revision&revision=1552970> and I
>> really don't want to repeat that effort for all my other codebases.  In
>> particular I can't imagine spending customer paid time getting an
>> inhouse codebase build again by removing self-closing HTML tags from
>> Javadocs. :-)

If you don't want the checks, use -Xdoclint:none.  The checks are there 
to help
you generate legal compliant HTML docs from your javadoc comments. And
self-closing tags are not legal in HTML 4.01.

>>
>> Stefan
>>
>> [1] not quite, Ant's apt tests still fail.  Ant must be relying on some
>> internal API that has been changed but I'm not familiar enough with
>> either the apt tool nor the Ant task to judge here.
>