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

[Uwe Schindler]

> 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