First, as was pointed out earlier[1] in the original thread, the HTML 4 spec
does not mention the existence of self-closing elements, and in that
message,
David makes a good point that <br> is defined to not have an end tag,
making the <br/> syntax doubly questionable.
So what does "doclint" stand for? Read it as "doc lint" meaning it is to
javadoc comments what -Xlint is to javac and lint is to C code. In other
words, it is intended to be used to point out questionable (or erroneous)
input. The ";" in "for (Item i: list);" is totally legal, the cast in
"String s =
(String) "abc"; are both legal, but we do not think it unreasonable to
highlight them in code, along with all the other -X lint warnings. So
too with -Xdoclint messages regarding javadoc comments.
Yes, you can say that all the browsers (now) accept this syntax -- but
the design intent of -Xdoclint was to highlight issues that might cause
a validator to give comments. For far too long, the javadoc tool itself
has generated bad code, and so the general goal in the ongoing javadoc
TLC has been that given valid input, javadoc should generate valid output,
where "valid" means "conforms to the published DOCTYPE" and accepted
by a standard recognized validator, such as the one I cited at w3c.org.
I would /strongly/ prefer that we not revert back to "is the output from
javadoc
accepted by all browsers?".
Should -Xdoclint be opt-in or opt-out? For what its worth, this was
always a controversial decision, because of the potential for
discussions like
this. We've ended up with a compromise. It is opt-in at javac time,
which is
when I'd expect most interested developers to want to use it -- as a
developer,
I want to see the doclint feedback at the time I'm writing my doc comments,
when I'm in the compile-edit-test cycle. But it is not enabled by
default for
javac. But it is enabled by default in javadoc at doc-generation time.
When you're generating docs, it is good for folk to know that the docs do
not conform to the declared standard (i.e. HTML 4.01) If you're not
interested
in the feedback, you can disable it easily enough. If you are interested,
a global replace of <br/> to <br> should not be an onerous task in any
modern IDE.
Finally, another message [2] in the thread mentioned HTML 5. That is
definitely
on the upcoming radar. I would also like to see javadoc more forgiving in
its input while still generating conformant output. Yes, that might mean
fixing
up minor transgressions. But not today.
-- Jon
[1]
http://mail.openjdk.java.net/pipermail/core-libs-dev/2013-July/019262.html
[2]
http://mail.openjdk.java.net/pipermail/core-libs-dev/2013-July/019264.html
On 07/25/2013 01:22 PM, Nick Williams wrote:
Jonathan, I don't see the "confirmation that this is not legal HTML" that you
reference. I see a warning that some browsers may not interpret it correctly. But IE 5+
and all Firefox, Chrome, Netscape, Opera, etc. versions interpret it correctly.
I understand your point about the spec not specifically allowing it. HOWEVER, I
promise you there are TENS OF THOUSANDS of existing JavaDoc'd classes that will
break JavaDoc generation as a result of this change.
Maybe doclint (what does that stand for, by the way?) could be a default-off
feature instead of a default-on feature?
Nick
On Jul 25, 2013, at 1:59 PM, Jonathan Gibbons wrote:
The message about "self-closing element not allowed" is because self-closing elements are
not allowed in HTML 4. The message is generated by the new "doclint" feature available in
javac and javadoc, which is specifically intended to detect issues in javadoc comments. If you do
not wish to use the new doclint feature, you can disable it with -Xdoclint:none.
As confirmation that this is not legal HTML, try typing a code fragment such as
the following into the W3c validator at http://validator.w3.org/check
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<head>
<title>test</title>
</head>
<body>
<br/>
</body>
</html>
You will get the following warning:
1. /Line 6 <http://validator.w3.org/check#line-6>, Column 4/:
NET-enabling start-tag requires SHORTTAG YES
|<br*/*>|
For the current document, the validator interprets strings like
|<FOO />| according to legacy rules that break the expectations of
most authors and thus cause confusing warnings and error messages
from the validator. This interpretation is triggered by HTML 4
documents or other SGML-based HTML documents. To avoid the
messages, simply remove the "/" character in such contexts. NB: If
you expect |<FOO />| to be interpreted as an XML-compatible
"self-closing" tag, then you need to use XHTML or HTML5.
This warning and related errors may also be caused by an unquoted
attribute value containing one or more "/". Example: |<a
href=http://w3c.org>W3C</a>|. In such cases, the solution is to
put quotation marks around the value.
-- Jon
On 07/25/2013 11:14 AM, Alan Bateman wrote:
Re: Invalid "self-closing element not allowed" JavaDoc error.eml
Subject:
Re: Invalid "self-closing element not allowed" JavaDoc error
From:
"David M. Lloyd" <david.ll...@redhat.com>
Date:
07/25/2013 10:41 AM
To:
core-libs-dev@openjdk.java.net
On 07/25/2013 12:27 PM, Nick Williams wrote:
My apologies if this is not the right place to address this. If so, please
forgive and direct me to the correct list.
There are a lot of people/projects complaining about Java 8's new "self-closing element not allowed"
error when compiling JavaDoc that has legal <br /> tags in it (just google "self-closing element not
allowed" in quotes). Some (including myself) are asking, "Why should we fix this? The problem is not in
the JavaDoc, it's in the JavDoc compiler." However, I haven't been able to find anyone who has actually
broached the subject on any mailing lists.
<br /> is completely legal. While it is not strictly required by the HTML standard (unless
you're using XHTML), using self-closing tags is /preferred/ because it's more obvious what the
intention is. Perhaps most importantly, <br /> is supported on 100% of browsers and is used
throughout JavaDoc all over the place. I have a feeling that once more projects start compiling on a
released Java 8, this is going to make a fair number of people angry that hey have to "fix"
(read: needlessly change) potentially thousands of classes' worth of JavaDoc.
What was the motivation behind the new "self-closing element not allowed" check
and how can we make it go away?
Not really having a stake in this, I just want to observe a couple things.
First, from what I can see, the HTML 4.x specifications make no reference to
self-closing elements or their syntactical realization. As far as I can tell
(not being any kind of SGML expert), self-closing elements are not valid or
meaningful HTML according to its SGML definition.
Finally, even if they were allowed, the BR tag is explicitly defined to forbid
an end tag; self-closing elements imply an end tag (at least they do in XML,
which appears to be the next-nearest concrete specification that has anything
to say on the matter).
See http://www.w3.org/TR/html401/struct/text.html#edef-BR for more info.
So I'm curious when you say "using self-closing tags is /preferred/", do you
have any sources to cite?
--
- DML
Re: Invalid "self-closing element not allowed" JavaDoc error.eml
Subject:
Re: Invalid "self-closing element not allowed" JavaDoc error
From:
Stephen Colebourne <scolebou...@joda.org>
Date:
07/25/2013 10:59 AM
To:
core-libs-dev@openjdk.java.net
Its complicated, see for example:
http://stackoverflow.com/questions/3558119/are-self-closing-tags-valid-in-html5
The key point here is not whether its in the standard or not, but what
people actually*do*.
There is no doubt in my mind that <br /> br space slash is very common
indeed. Its certainly my default. The javadoc validator should be as
lenient as browsers are in this case.
Stephen
On 25 July 2013 18:41, David M. Lloyd<david.ll...@redhat.com> wrote:
On 07/25/2013 12:27 PM, Nick Williams wrote:
My apologies if this is not the right place to address this. If so, please
forgive and direct me to the correct list.
There are a lot of people/projects complaining about Java 8's new
"self-closing element not allowed" error when compiling JavaDoc that has
legal <br /> tags in it (just google "self-closing element not allowed" in
quotes). Some (including myself) are asking, "Why should we fix this? The
problem is not in the JavaDoc, it's in the JavDoc compiler." However, I
haven't been able to find anyone who has actually broached the subject on
any mailing lists.
<br /> is completely legal. While it is not strictly required by the HTML
standard (unless you're using XHTML), using self-closing tags is/preferred/
because it's more obvious what the intention is. Perhaps most importantly,
<br /> is supported on 100% of browsers and is used throughout JavaDoc all
over the place. I have a feeling that once more projects start compiling on
a released Java 8, this is going to make a fair number of people angry that
hey have to "fix" (read: needlessly change) potentially thousands of
classes' worth of JavaDoc.
What was the motivation behind the new "self-closing element not allowed"
check and how can we make it go away?
Not really having a stake in this, I just want to observe a couple things.
First, from what I can see, the HTML 4.x specifications make no reference to
self-closing elements or their syntactical realization. As far as I can
tell (not being any kind of SGML expert), self-closing elements are not
valid or meaningful HTML according to its SGML definition.
Finally, even if they were allowed, the BR tag is explicitly defined to
forbid an end tag; self-closing elements imply an end tag (at least they do
in XML, which appears to be the next-nearest concrete specification that has
anything to say on the matter).
Seehttp://www.w3.org/TR/html401/struct/text.html#edef-BR for more info.
So I'm curious when you say "using self-closing tags is/preferred/", do you
have any sources to cite?
--
- DML
