Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Commons Developers List" <dev@commons.apache.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8;
 format=flowed
Content-Transfer-Encoding: 7bit
Date: Wed, 28 Sep 2016 15:06:24 +0200
From: Gilles <gilles@harfang.homelinux.org>
To: <dev@commons.apache.org>
Subject: Re: [1/4] commons-rng git commit: Fixed the javadoc errors with
 Java 8
In-Reply-To: <cacdbd5db7de4c58bded7a6db68feb0b@git.apache.org>
References: <cacdbd5db7de4c58bded7a6db68feb0b@git.apache.org>
Message-ID: <5cfd91175be15ecaecdf838151c4bc0c@scarlet.be>
User-Agent: Scarlet Webmail
X-DCC-scarlet.be-Metrics: sif; whitelist
X-Virus-Scanned: clamav-milter 0.98.1-exp at sif
X-Virus-Status: Clean
archived-at: Wed, 28 Sep 2016 13:06:33 -0000

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 <ebourg@apache.org>
> Authored: Wed Sep 28 10:05:47 2016 +0200
> Committer: Emmanuel Bourg <ebourg@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.&nbsp;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