Thanks for the non-trivial details that make the change
understandable.
It would have been nice to post this information on the ML,
before applying the changes.
The more so that the issue was encountered by several people
in different components, and IIRC now, the consensus (or
workaround) had been to indeed disable "doclint".
With this new specification (where laziness is not forgiven),
it is even more important than it was (when I raised the
issue, and nobody gave a damn) to decide together how to
layout Javadoc comments (so that they are both readable in
code and compliant).
I've used <p></p> to create a _paragraph_:
"a distinct section of a piece of writing, usually dealing
with a single theme and indicated by a new line, indentation,
or numbering"
Your usage of <p>, even if compliant with the HTML spec, does
not comply with the above definition, and makes the Javadoc
difficult to read.
Is there an HTML element which we can use to make a paragraph
(that would allow sample code or a list within it)?
Gilles
On Thu, 29 Sep 2016 00:59:48 +0200, Emmanuel Bourg wrote:
Le 28/09/2016 à 16:40, Gilles a écrit :
They are not trivial issues, because they are not seen by everyone.
I'm not sure I have the same definition of "trivial" in my dictionary
:)
Below, you refer to HTML 5.
Is the "javadoc" tool assuming that its input is valid HTML 5?
Javadoc in Java 8 is HTML 4 compliant, it'll switch to HTML 5 in Java
9
(see JEP 224 [1]).
But the rule I mentioned isn't new in HTML 5, it existed before:
https://www.w3.org/TR/html401/struct/text.html#edef-P
"The P element represents a paragraph. It cannot contain block-level
elements (including P itself)."
Several years ago, I raise the issue of writing "valid" HTML/XHTML.
At the time, the answer had been that the Javadoc specification
referred to an older HTML version, and that it was not going to
change, and thus not worth updating the docs in any consistent
way with the recommendation of W3C.
Has that changed?
It changed with Java 8 enforcing the correctness of the HTML output.
No, I purposefully removed that option before rerunning "mvn clean
site"!
Perhaps you've run into
https://issues.apache.org/jira/browse/RNG-1
All I'm saying is that change must be clarified because it is
definitely
not "Java 8" as such that causes the trouble.
Are you using OpenJDK 8 on Debian/Ubuntu? doclint is disabled by
default
on these systems [2].
Emmanuel Bourg
[1] http://openjdk.java.net/jeps/224
[2]
https://sources.debian.net/src/openjdk-8/8u102-b14.1-2/debian/patches/disable-doclint-by-default.diff/
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
