Testing Apache Ant against JDK 8 EA builds

[Zhong Yu]

On Tue, Jan 7, 2014 at 1:56 AM, Zhong Yu <zhong.j.yu at gmail.com> wrote:
> 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.

That is *not* in the best interest of javadoc.

Also note that, people who write <br/> do so from their own "moral"
ground, they think it is the right thing to do.

Javadoc can choose to produce strict html 4.01, but it doesn't have to
only consume strict html 4.01.

Zhong Yu

> 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.
>>>
>>>
>>