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.
