JDK 8's javadoc tool no longer copies doc-files folders

[Jonathan Gibbons]

On 02/25/2013 11:00 AM, Uwe Schindler wrote:
>> On 02/25/2013 10:42 AM, Uwe Schindler wrote:
>>> Hi,
>>>
>>>> We are aware of the issues caused by enabling doclint by default in
>>>> javadoc -- but it was a deliberate decision to enable the feature by
>>>> default, so that authors are aware of problems in their doc comments.
>>>> You can avoid the messages by fixing the issues in the doc comments,
>>>> or by disabling some of all of the messages with the -Xdoclint option.
>>> Wouldn't be the level of "warning" the right choice? The current approach
>> fails the build.
>>> Uwe
>>>
>> a) Warnings get overlooked.
>>
>> b) As far as HTML issues are concerned, the general approach is to give errors
>> where the issues would likely cause a downstream issue if the generated
>> output were to run run through a validator. So an invalid entity is an error,
>> pure an simple
>> -- it gives rise to generated output that would contain an invalid
>> entity.   Errors are
>> also used in other serious cases, such as an @param or @see that references
>> a non-existent entity in the Java source code.   These are serious doc
>> problems
>> that warrant fixing, and deserve to "break the build" until the issue is fixed.
>>
>> -- Jon
> I agree that an error for invalid @see references is a good thing. Our own htmltidy-based linter in Apache Lucene's build does exactly check this (it follows all links in the generated HTML). The main problem I see is a too-strict checking for e.g. a <p> always needs a </p>, which is not needed according to HTML4 and HTML5 (only XHTML enforces this because XHTML is XML based and needs correctly closed tags, not SGML). But Javadocs are not XHTML.
>
> In our case most errors were caused by this <p></p> issue (and similar for other element names), as we don’t have broken @see/@link in Lucene. If this would be fixed in future builds, we are happy to use the doclint feature!
>
> Uwe
>

The issue with <p> apparently requiring </p> was a bug that has been 
fixed.  (The bug was that optional end tags were not correctly handled 
at the top level.) The general intent is that javadoc/doclint should 
accept HTML that is valid for 3.2 or 4.01. Going forward, it would be 
nice to eventually settle on HTML 5, and to generate HTML 5 output, but 
"not today".

-- Jon