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
