Return-Path: <commits-return-52899-archive-asf-public=cust-asf.ponee.io@commons.apache.org>
X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io
Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io
Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183])
	by cust-asf2.ponee.io (Postfix) with ESMTP id 43864200B70
	for <archive-asf-public-internal@cust-asf2.ponee.io>; Sat, 27 Aug 2016 15:24:04 +0200 (CEST)
Received: by cust-asf.ponee.io (Postfix)
	id 42010160A89; Sat, 27 Aug 2016 13:24:04 +0000 (UTC)
Delivered-To: archive-asf-public@cust-asf.ponee.io
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
	by cust-asf.ponee.io (Postfix) with SMTP id 606B7160AA6
	for <archive-asf-public@cust-asf.ponee.io>; Sat, 27 Aug 2016 15:24:03 +0200 (CEST)
Received: (qmail 36696 invoked by uid 500); 27 Aug 2016 13:24:02 -0000
Mailing-List: contact commits-help@commons.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@commons.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@commons.apache.org>
List-Post: <mailto:commits@commons.apache.org>
List-Id: <commits.commons.apache.org>
Reply-To: dev@commons.apache.org
Delivered-To: mailing list commits@commons.apache.org
Received: (qmail 36438 invoked by uid 99); 27 Aug 2016 13:24:02 -0000
Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23)
    by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 27 Aug 2016 13:24:02 +0000
Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33)
	id 39706DFA1E; Sat, 27 Aug 2016 13:24:02 +0000 (UTC)
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: erans@apache.org
To: commits@commons.apache.org
Date: Sat, 27 Aug 2016 13:24:03 -0000
Message-Id: <948a82a6bc6c4401acc7efd800ac5028@git.apache.org>
In-Reply-To: <8d9ea797f0134a039f89956ba420acfa@git.apache.org>
References: <8d9ea797f0134a039f89956ba420acfa@git.apache.org>
X-Mailer: ASF-Git Admin Mailer
Subject: [2/2] commons-rng git commit: Javadoc.
archived-at: Sat, 27 Aug 2016 13:24:04 -0000

Javadoc.


Project: http://git-wip-us.apache.org/repos/asf/commons-rng/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-rng/commit/5d857818
Tree: http://git-wip-us.apache.org/repos/asf/commons-rng/tree/5d857818
Diff: http://git-wip-us.apache.org/repos/asf/commons-rng/diff/5d857818

Branch: refs/heads/master
Commit: 5d8578185de6ef11561073b36d5a66ca851a40bc
Parents: 493ed59
Author: Gilles <erans@apache.org>
Authored: Sat Aug 27 17:22:18 2016 +0200
Committer: Gilles <erans@apache.org>
Committed: Sat Aug 27 17:22:18 2016 +0200

----------------------------------------------------------------------
 .../org/apache/commons/rng/RandomSource.java    | 77 ++++++++++++++++----
 1 file changed, 63 insertions(+), 14 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/commons-rng/blob/5d857818/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 6b2f5fc..eb318a1 100644
--- a/src/main/java/org/apache/commons/rng/RandomSource.java
+++ b/src/main/java/org/apache/commons/rng/RandomSource.java
@@ -85,6 +85,13 @@ import org.apache.commons.rng.internal.source64.TwoCmres;
  * by this library may <i>not</i> be the same as the sequences produced
  * by other implementations of the same algorithm!
  * </p>
+ * <p>
+ * For each algorithm, the Javadoc mentions the "ideal" size of the seed,
+ * meaning the number of {@code int} or {@code long} values that is neither
+ * too large (i.e. some of the seed is useless) or too small (i.e. an
+ * internal procedure will fill the state with redundant information
+ * computed from the given seed).
+ * </p>
  *
  * <p>
  * This class provides methods to generate random seeds (single values
@@ -142,73 +149,115 @@ import org.apache.commons.rng.internal.source64.TwoCmres;
 public enum RandomSource {
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source32.JDKRandom}.
-     * Native seed type: {@code Long}.
+     * <ul>
+     *  <li>Native seed type: {@code Long}.</li>
+     *  <li>Native seed size: 1.</li>
+     * </ul>
      */
     JDK(ProviderBuilder.RandomSourceInternal.JDK),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source32.Well512a}.
-     * Native seed type: {@code int[]}.
+     * <ul>
+     *  <li>Native seed type: {@code int[]}.</li>
+     *  <li>Native seed size: 16.</li>
+     * </ul>
      */
     WELL_512_A(ProviderBuilder.RandomSourceInternal.WELL_512_A),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source32.Well1024a}.
-     * Native seed type: {@code int[]}.
+     * <ul>
+     *  <li>Native seed type: {@code int[]}.</li>
+     *  <li>Native seed size: 32.</li>
+     * </ul>
      */
     WELL_1024_A(ProviderBuilder.RandomSourceInternal.WELL_1024_A),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source32.Well19937a}.
-     * Native seed type: {@code int[]}.
+     * <ul>
+     *  <li>Native seed type: {@code int[]}.</li>
+     *  <li>Native seed size: 624.</li>
+     * </ul>
      */
     WELL_19937_A(ProviderBuilder.RandomSourceInternal.WELL_19937_A),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source32.Well19937c}.
-     * Native seed type: {@code int[]}.
+     * <ul>
+     *  <li>Native seed type: {@code int[]}.</li>
+     *  <li>Native seed size: 624.</li>
+     * </ul>
      */
     WELL_19937_C(ProviderBuilder.RandomSourceInternal.WELL_19937_C),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source32.Well44497a}.
-     * Native seed type: {@code int[]}.
+     * <ul>
+     *  <li>Native seed type: {@code int[]}.</li>
+     *  <li>Native seed size: 1391.</li>
+     * </ul>
      */
     WELL_44497_A(ProviderBuilder.RandomSourceInternal.WELL_44497_A),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source32.Well44497b}.
-     * Native seed type: {@code int[]}.
+     * <ul>
+     *  <li>Native seed type: {@code int[]}.</li>
+     *  <li>Native seed size: 1391.</li>
+     * </ul>
      */
     WELL_44497_B(ProviderBuilder.RandomSourceInternal.WELL_44497_B),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source32.MersenneTwister}.
-     * Native seed type: {@code int[]}.
+     * <ul>
+     *  <li>Native seed type: {@code int[]}.</li>
+     *  <li>Native seed size: 624.</li>
+     * </ul>
      */
     MT(ProviderBuilder.RandomSourceInternal.MT),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source32.ISAACRandom}.
-     * Native seed type: {@code int[]}.
+     * <ul>
+     *  <li>Native seed type: {@code int[]}.</li>
+     *  <li>Native seed size: 256.</li>
+     * </ul>
      */
     ISAAC(ProviderBuilder.RandomSourceInternal.ISAAC),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source64.SplitMix64}.
-     * Native seed type: {@code Long}.
+     * <ul>
+     *  <li>Native seed type: {@code Long}.</li>
+     *  <li>Native seed size: 1.</li>
+     * </ul>
      */
     SPLIT_MIX_64(ProviderBuilder.RandomSourceInternal.SPLIT_MIX_64),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source64.XorShift1024Star}.
-     * Native seed type: {@code long[]}.
+     * <ul>
+     *  <li>Native seed type: {@code long[]}.</li>
+     *  <li>Native seed size: 16.</li>
+     * </ul>
      */
     XOR_SHIFT_1024_S(ProviderBuilder.RandomSourceInternal.XOR_SHIFT_1024_S),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source64.TwoCmres}.
-     * Native seed type: {@code Integer}.
+     * <ul>
+     *  <li>Native seed type: {@code Integer}.</li>
+     *  <li>Native seed size: 1.</li>
+     * </ul>
      */
     TWO_CMRES(ProviderBuilder.RandomSourceInternal.TWO_CMRES),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source64.TwoCmres},
      * with explicit selection of the two subcycle generators.
-     * Native seed type: {@code Integer}.
+     * <ul>
+     *  <li>Native seed type: {@code Integer}.</li>
+     *  <li>Native seed size: 1.</li>
+     * </ul>
      */
     TWO_CMRES_SELECT(ProviderBuilder.RandomSourceInternal.TWO_CMRES_SELECT),
     /**
      * Source of randomness is {@link org.apache.commons.rng.internal.source64.MersenneTwister64}.
-     * Native seed type: {@code long[]}.
+     * <ul>
+     *  <li>Native seed type: {@code long[]}.</li>
+     *  <li>Native seed size: 312.</li>
+     * </ul>
      */
     MT_64(ProviderBuilder.RandomSourceInternal.MT_64);