Testing Apache Ant against JDK 8 EA builds

[Zhong Yu]

I had a comment here:
http://mail.openjdk.java.net/pipermail/core-libs-dev/2013-July/019308.html

Regarding strict HTML 4.01 compliance - majority of people don't care.
If javadoc takes a moral stand on this issue, a lot of people will be
annoyed and angry. That's in the best interest of javadoc as a tool.
Strict compliance should be an opt-in for the tiny minority who do
care.

Zhong Yu



On Mon, Jan 6, 2014 at 3:22 PM, Jonathan Gibbons
<jonathan.gibbons at oracle.com> wrote:
>
> 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.
>>
>>
>