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 13:06:24 UTC
Re: [1/4] commons-rng git commit: Fixed the javadoc errors with
Java 8
Emmanuel,
On Wed, 28 Sep 2016 08:54:50 -0000, ebourg@apache.org wrote:
> Repository: commons-rng
> Updated Branches:
> refs/heads/master fcc9da888 -> fd22dc61f
>
>
> Fixed the javadoc errors with Java 8
I use Java 8 and did not get any errors when generating the apidocs.
Unless I'm missing something, the above message does not correspond
to the change in this commit.
The changes themselves contradict usage of the <p> HTML tag: <p> and
</p> enclose a paragraph, not a headline.
So I think that this change should be reverted.
Then please let us know what problems you encountered so we can
decide _together_ on how we want Javadoc to be written for this
component (and possibly others).
Thanks,
Gilles
> Project: http://git-wip-us.apache.org/repos/asf/commons-rng/repo
> Commit:
> http://git-wip-us.apache.org/repos/asf/commons-rng/commit/41830f7d
> Tree:
> http://git-wip-us.apache.org/repos/asf/commons-rng/tree/41830f7d
> Diff:
> http://git-wip-us.apache.org/repos/asf/commons-rng/diff/41830f7d
>
> Branch: refs/heads/master
> Commit: 41830f7d94bfdb53c04b5c76986f3272fe6cfe64
> Parents: fcc9da8
> Author: Emmanuel Bourg <eb...@apache.org>
> Authored: Wed Sep 28 10:05:47 2016 +0200
> Committer: Emmanuel Bourg <eb...@apache.org>
> Committed: Wed Sep 28 10:05:47 2016 +0200
>
>
> ----------------------------------------------------------------------
> .../org/apache/commons/rng/RandomSource.java | 28
> ++++++++------------
> .../rng/internal/source32/MersenneTwister.java | 2 +-
> .../internal/source64/MersenneTwister64.java | 2 +-
> .../commons/rng/internal/source64/TwoCmres.java | 5 ++--
> .../rng/internal/util/NumberFactory.java | 17 ++++++------
> 5 files changed, 24 insertions(+), 30 deletions(-)
>
> ----------------------------------------------------------------------
>
>
>
> http://git-wip-us.apache.org/repos/asf/commons-rng/blob/41830f7d/src/main/java/org/apache/commons/rng/RandomSource.java
>
> ----------------------------------------------------------------------
> diff --git a/src/main/java/org/apache/commons/rng/RandomSource.java
> b/src/main/java/org/apache/commons/rng/RandomSource.java
> index 0c22419..27b67bb 100644
> --- a/src/main/java/org/apache/commons/rng/RandomSource.java
> +++ b/src/main/java/org/apache/commons/rng/RandomSource.java
> @@ -23,8 +23,8 @@ import
> org.apache.commons.rng.internal.util.SeedFactory;
>
> /**
> * This class provides the API for creating generators of random
> numbers.
> - * <p>
> - * Usage examples:
> + *
> + * <p>Usage examples:</p>
> * <pre><code>
> * UniformRandomProvider rng =
> RandomSource.create(RandomSource.MT);
> * </code></pre>
> @@ -41,7 +41,8 @@ import
> org.apache.commons.rng.internal.util.SeedFactory;
> * where the first argument to method {@code create} is the
> identifier
> * of the generator's concrete implementation, and the second the is
> the
> * (optional) seed.
> - * <br>
> + *
> + * <p>
> * In the first form, a random seed will be {@link SeedFactory
> generated
> * automatically}; in the second form, a fixed seed is used; a
> random seed
> * is explicitly generated in the third form.
> @@ -105,9 +106,11 @@ import
> org.apache.commons.rng.internal.util.SeedFactory;
> * or arrays of values, of {@code int} or {@code long} types) that
> can
> * be passed to the {@link
> RandomSource#create(RandomSource,Object,Object[])
> * generators factory method}.
> - * <br>
> + * </p>
> + * <p>
> * Although the seed-generating methods defined in this class will
> likely
> * return different values each time they are called, there is no
> guarantee:
> + * </p>
> * <ul>
> * <li>
> * In any sub-sequence, it is <a
> href="https://en.wikipedia.org/wiki/Birthday_problem">
> @@ -126,7 +129,6 @@ import
> org.apache.commons.rng.internal.util.SeedFactory;
> * or <a
> href="http://simul.iro.umontreal.ca/testu01/tu01.html">TestU01</a>.
> * </li>
> * </ul>
> - * </p>
> *
> * <p>
> * The current implementations have no provision for producing
> non-overlapping
> @@ -365,12 +367,10 @@ public enum RandomSource {
> /**
> * Creates a random number generator with a random seed.
> *
> - * <p>
> - * Example of usage:
> + * <p>Example of usage:</p>
> * <pre><code>
> * UniformRandomProvider rng =
> RandomSource.create(RandomSource.MT);
> * </code></pre>
> - * </p>
> *
> * @param source RNG type.
> * @return the RNG.
> @@ -382,15 +382,12 @@ public enum RandomSource {
> /**
> * Creates a random number generator with the given {@code
> seed}.
> *
> - * <p>
> - * Example of usage:
> + * <p>Example of usage:</p>
> * <pre><code>
> * UniformRandomProvider rng =
> RandomSource.create(RandomSource.TWO_CMRES_SELECT, 26219, 6, 9);
> * </code></pre>
> - * </p>
> *
> - * <p>
> - * Valid types for the {@code seed} are:
> + * <p>Valid types for the {@code seed} are:</p>
> * <ul>
> * <li>{@code Integer} (or {@code int})</li>
> * <li>{@code Long} (or {@code long})</li>
> @@ -398,10 +395,8 @@ public enum RandomSource {
> * <li>{@code long[]}</li>
> * <li>{@code byte[]}</li>
> * </ul>
> - * </p>
> *
> - * <p>
> - * Notes:
> + * <p>Notes:</p>
> * <ul>
> * <li>
> * When the seed type passed as argument is more complex (i.e.
> more
> @@ -419,7 +414,6 @@ public enum RandomSource {
> * {@code null}, the size of the generated array will be 128.
> * </li>
> * </ul>
> - * </p>
> *
> * @param source RNG type.
> * @param seed Seed value. It can be {@code null} (in which
> case a
>
>
> http://git-wip-us.apache.org/repos/asf/commons-rng/blob/41830f7d/src/main/java/org/apache/commons/rng/internal/source32/MersenneTwister.java
>
> ----------------------------------------------------------------------
> diff --git
>
> a/src/main/java/org/apache/commons/rng/internal/source32/MersenneTwister.java
>
> b/src/main/java/org/apache/commons/rng/internal/source32/MersenneTwister.java
> index e53ac4e..0626a7d 100644
> ---
>
> a/src/main/java/org/apache/commons/rng/internal/source32/MersenneTwister.java
> +++
>
> b/src/main/java/org/apache/commons/rng/internal/source32/MersenneTwister.java
> @@ -49,7 +49,7 @@ import
> org.apache.commons.rng.internal.util.NumberFactory;
> * and Takuji Nishimura. Here is their original copyright:
> * </p>
> *
> - * <table border="0" width="80%" cellpadding="10" align="center"
> bgcolor="#E0E0E0">
> + * <table border="0" width="80%" cellpadding="10"
> style="background-color: #E0E0E0" summary="Mersenne Twister licence">
> * <tr><td>Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji
> Nishimura,
> * All rights reserved.</td></tr>
> *
>
>
> http://git-wip-us.apache.org/repos/asf/commons-rng/blob/41830f7d/src/main/java/org/apache/commons/rng/internal/source64/MersenneTwister64.java
>
> ----------------------------------------------------------------------
> diff --git
>
> a/src/main/java/org/apache/commons/rng/internal/source64/MersenneTwister64.java
>
> b/src/main/java/org/apache/commons/rng/internal/source64/MersenneTwister64.java
> index bee7ece..8943ba6 100644
> ---
>
> a/src/main/java/org/apache/commons/rng/internal/source64/MersenneTwister64.java
> +++
>
> b/src/main/java/org/apache/commons/rng/internal/source64/MersenneTwister64.java
> @@ -35,7 +35,7 @@ import
> org.apache.commons.rng.internal.util.NumberFactory;
> * Here is their original copyright:
> * </p>
> *
> - * <table border="0" width="80%" cellpadding="10" align="center"
> bgcolor="#E0E0E0">
> + * <table border="0" width="80%" cellpadding="10"
> style="background-color: #E0E0E0" summary="Mersenne Twister licence">
> * <tr><td>Copyright (C) 2004, Makoto Matsumoto and Takuji
> Nishimura,
> * All rights reserved.</td></tr>
> *
>
>
> http://git-wip-us.apache.org/repos/asf/commons-rng/blob/41830f7d/src/main/java/org/apache/commons/rng/internal/source64/TwoCmres.java
>
> ----------------------------------------------------------------------
> diff --git
>
> a/src/main/java/org/apache/commons/rng/internal/source64/TwoCmres.java
>
> b/src/main/java/org/apache/commons/rng/internal/source64/TwoCmres.java
> index 8afe220..2427f60 100644
> ---
> a/src/main/java/org/apache/commons/rng/internal/source64/TwoCmres.java
> +++
> b/src/main/java/org/apache/commons/rng/internal/source64/TwoCmres.java
> @@ -23,13 +23,12 @@ import
> org.apache.commons.rng.internal.util.NumberFactory;
>
> /**
> * Random number generator designed by Mark D. Overton.
> - * <p>
> - * It is one of the many generators described by the author in the
> following article series:
> + *
> + * <p>It is one of the many generators described by the author in
> the following article series:</p>
> * <ul>
> * <li><a
>
> href="http://www.drdobbs.com/tools/fast-high-quality-parallel-random-number/229625477">Part
> one</a></li>
> * <li><a
>
> href="http://www.drdobbs.com/tools/fast-high-quality-parallel-random-number/231000484">Part
> two</a></li>
> * </ul>
> - * </p>
> *
> * @since 1.0
> */
>
>
> http://git-wip-us.apache.org/repos/asf/commons-rng/blob/41830f7d/src/main/java/org/apache/commons/rng/internal/util/NumberFactory.java
>
> ----------------------------------------------------------------------
> diff --git
>
> a/src/main/java/org/apache/commons/rng/internal/util/NumberFactory.java
>
> b/src/main/java/org/apache/commons/rng/internal/util/NumberFactory.java
> index b769db6..22f1d16 100644
> ---
> a/src/main/java/org/apache/commons/rng/internal/util/NumberFactory.java
> +++
> b/src/main/java/org/apache/commons/rng/internal/util/NumberFactory.java
> @@ -112,14 +112,14 @@ public final class NumberFactory {
>
> /**
> * Creates an {@code int} from a {@code long}, using the high
> order bits.
> - * <p>
> - * The returned value is such that if
> + *
> + * <p>The returned value is such that if</p>
> * <pre><code>
> * vL = extractLo(v);
> * vH = extractHi(v);
> * </code></pre>
> - * then {@code v} is equal to {@link #makeLong(int,int)
> makeLong(vH, vL)}.
> - * </p>
> + *
> + * <p>then {@code v} is equal to {@link #makeLong(int,int)
> makeLong(vH, vL)}.</p>
> *
> * @param v Number.
> * @return an {@code int} value made from the most significant
> bits
> @@ -131,14 +131,15 @@ public final class NumberFactory {
>
> /**
> * Creates an {@code int} from a {@code long}, using the low
> order bits.
> - * <p>
> - * The returned value is such that if
> + *
> + * <p>The returned value is such that if</p>
> + *
> * <pre><code>
> * vL = extractLo(v);
> * vH = extractHi(v);
> * </code></pre>
> - * then {@code v} is equal to {@link #makeLong(int,int)
> makeLong(vH, vL)}.
> - * </p>
> + *
> + * <p>then {@code v} is equal to {@link #makeLong(int,int)
> makeLong(vH, vL)}.</p>
> *
> * @param v Number.
> * @return an {@code int} value made from the least significant
> bits
---------------------------------------------------------------------
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
[RNG] How to write Javadoc (Was: ... commit: Fixed the javadoc
errors with Java 8)
Posted by Gilles <gi...@harfang.homelinux.org>.
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: [1/4] commons-rng git commit: Fixed the javadoc errors with Java
8
Posted by Emmanuel Bourg <eb...@apache.org>.
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: [1/4] commons-rng git commit: Fixed the javadoc errors with
Java 8
Posted by Gilles <gi...@harfang.homelinux.org>.
On Wed, 28 Sep 2016 15:39:44 +0200, Emmanuel Bourg wrote:
> Le 28/09/2016 � 15:06, Gilles a �crit :
>
>> I use Java 8 and did not get any errors when generating the apidocs.
>>
>> Unless I'm missing something, the above message does not correspond
>> to the change in this commit.
>>
>> The changes themselves contradict usage of the <p> HTML tag: <p> and
>> </p> enclose a paragraph, not a headline.
>>
>> So I think that this change should be reverted.
>>
>> Then please let us know what problems you encountered so we can
>> decide _together_ on how we want Javadoc to be written for this
>> component (and possibly others).
>
> Do we really need to decide together how to fix trivial Javadoc
> issues?
They are not trivial issues, because they are not seen by everyone.
> I wanted to regenerate the Javadoc and I got several errors when
> running
> "mvn javadoc:javadoc" on Windows 7 with Java 8u91 and Maven 3.3.9.
> <ul>
> and <code> enclosed in <p> caused the issue (this is not allowed by
> the
> HTML specification [1]).
Below, you refer to HTML 5.
Is the "javadoc" tool assuming that its input is valid HTML 5?
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?
> So I simply changed:
>
> <p>blah blah:
> <ul>
> <li>Blah</li>
> </ul>
> </p>
>
> into the visually equivalent:
>
> <p>blah blah:</p>
> <ul>
> <li>Blah</li>
> </ul>
>
> You didn't see the errors because -Xdoclint:none is enabled for the
> site
> phase.
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.
Gilles
>
> Emmanuel Bourg
>
> [1] https://www.w3.org/TR/html5/grouping-content.html#the-p-element
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [1/4] commons-rng git commit: Fixed the javadoc errors with Java
8
Posted by Emmanuel Bourg <eb...@apache.org>.
Le 28/09/2016 � 15:06, Gilles a �crit :
> I use Java 8 and did not get any errors when generating the apidocs.
>
> Unless I'm missing something, the above message does not correspond
> to the change in this commit.
>
> The changes themselves contradict usage of the <p> HTML tag: <p> and
> </p> enclose a paragraph, not a headline.
>
> So I think that this change should be reverted.
>
> Then please let us know what problems you encountered so we can
> decide _together_ on how we want Javadoc to be written for this
> component (and possibly others).
Do we really need to decide together how to fix trivial Javadoc issues?
I wanted to regenerate the Javadoc and I got several errors when running
"mvn javadoc:javadoc" on Windows 7 with Java 8u91 and Maven 3.3.9. <ul>
and <code> enclosed in <p> caused the issue (this is not allowed by the
HTML specification [1]). So I simply changed:
<p>blah blah:
<ul>
<li>Blah</li>
</ul>
</p>
into the visually equivalent:
<p>blah blah:</p>
<ul>
<li>Blah</li>
</ul>
You didn't see the errors because -Xdoclint:none is enabled for the site
phase.
Emmanuel Bourg
[1] https://www.w3.org/TR/html5/grouping-content.html#the-p-element
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org