You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Gilles <gi...@harfang.homelinux.org> on 2016/09/28 23:37:37 UTC
[RNG] How to write Javadoc (Was: ... commit: Fixed the javadoc
errors with Java 8)
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: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [RNG] How to write Javadoc (Was: ... commit: Fixed the javadoc
errors with Java 8)
Posted by Gilles <gi...@harfang.homelinux.org>.
On Thu, 29 Sep 2016 10:55:07 +0200, Emmanuel Bourg wrote:
> Le 29/09/2016 � 01:37, Gilles a �crit :
>
>> 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".
>
> This is a wise workaround, fixing old Javadocs is a waste of time,
> but
> it isn't forbidden. If RNG had hundred of HTML errors I would have
> just
> disabled doclint when "mvn javadoc:javadoc" is used, but here it was
> easy to fix.
>
>
>> when I raised the issue, and nobody gave a damn
>
> Probably because Javadoc formatting issues aren't important enough
> for
> people to bother.
>
>
>> 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
>
> Maybe you should bring your concerns to the HTML Working Group then.
You known that this is not a very useful suggestion.
I've always assumed that <p> is for paragraph; obviously I
was wrong (for HTML and thus Javadoc).
In "xdoc", it seems that <p> can be used as I want.
IMHO, the term "paragraph" in the HTML spec is confusing
since a <p> that cannot be (fully) used as such.
The standardization committee surely knows that for a long
time, and is not going to change it now.
<div> is indeed what I should have used instead.
>> and makes the Javadoc difficult to read.
>
> The modification I made has no visual impact. These two snippets:
>
> <p>TOTO list:
> <ul>
> <li>One</li>
> <li>Two</li>
> <li>Three</li>
> </ul>
> Have a nice day!</p>
>
> and:
>
> <p>TOTO list:</p>
> <ul>
> <li>One</li>
> <li>Two</li>
> <li>Three</li>
> </ul>
> <p>Have a nice day!</p>
>
> are rendered identically in modern browsers.
That's not the point.
I think that developers read much more often the source code than
the rendered HTML (which is mostly for users); that's obviously
why I put emphasis on well and consistently formatted Javadoc.
> And the code readability
> isn't that different.
OK.
I don't agree.
I prefer:
<div>
TOTO list:
<ul>
<li>
One (description is usually longer than one word)
</li>
<li>
Two:
</li>
<li>
Three
</li>
</ul>
Have a nice day!
</div>
>> Is there an HTML element which we can use to make a paragraph
>> (that would allow sample code or a list within it)?
>
> You can use a <div> to mix inline text and lists, but you lose the
> paragraph semantic and the top/bottom margins.
Thanks for the reminder.
Gilles
>
> Emmanuel Bourg
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [RNG] How to write Javadoc (Was: ... commit: Fixed the javadoc
errors with Java 8)
Posted by Emmanuel Bourg <eb...@apache.org>.
Le 29/09/2016 � 01:37, Gilles a �crit :
> 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".
This is a wise workaround, fixing old Javadocs is a waste of time, but
it isn't forbidden. If RNG had hundred of HTML errors I would have just
disabled doclint when "mvn javadoc:javadoc" is used, but here it was
easy to fix.
> when I raised the issue, and nobody gave a damn
Probably because Javadoc formatting issues aren't important enough for
people to bother.
> 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
Maybe you should bring your concerns to the HTML Working Group then.
> and makes the Javadoc difficult to read.
The modification I made has no visual impact. These two snippets:
<p>TOTO list:
<ul>
<li>One</li>
<li>Two</li>
<li>Three</li>
</ul>
Have a nice day!</p>
and:
<p>TOTO list:</p>
<ul>
<li>One</li>
<li>Two</li>
<li>Three</li>
</ul>
<p>Have a nice day!</p>
are rendered identically in modern browsers. And the code readability
isn't that different.
> Is there an HTML element which we can use to make a paragraph
> (that would allow sample code or a list within it)?
You can use a <div> to mix inline text and lists, but you lose the
paragraph semantic and the top/bottom margins.
Emmanuel Bourg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [RNG] How to write Javadoc (Was: ... commit: Fixed the javadoc
errors with Java 8)
Posted by Emmanuel Bourg <eb...@apache.org>.
Le 29/09/2016 � 02:07, Gary Gregory a �crit :
> <p>
> I agree that paragraphs should be written like this.
> </p>
Personally for paragraphs I prefer this more compact form:
<p>Blah blah blah blah blah blah blah blah blah blah blah blah
blah blah blah blah blah blah blah blah blah blah blah blah</p>
And with a blank line between paragraphs.
Emmanuel Bourg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [RNG] How to write Javadoc (Was: ... commit: Fixed the javadoc
errors with Java 8)
Posted by Gary Gregory <ga...@gmail.com>.
<p>
I agree that paragraphs should be written like this.
</p>
Gary
On Wed, Sep 28, 2016 at 4:37 PM, Gilles <gi...@harfang.homelinux.org>
wrote:
>
> 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/debia
>> n/patches/disable-doclint-by-default.diff/
>>
>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
Java Persistence with Hibernate, Second Edition
<http://www.manning.com/bauer3/>
JUnit in Action, Second Edition <http://www.manning.com/tahchiev/>
Spring Batch in Action <http://www.manning.com/templier/>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory