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. 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 <[email protected]> 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. >> >> >
