MATH-1019

Removed dead link in Javadoc; added entry to original reference
in "LICENCE" file.


git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1513501 13f79535-47bb-0310-9956-ffa450edef68

LICENSE.txt

@@ -385,3 +385,16 @@ Th Orekit library is described at:
   https://www.orekit.org/forge/projects/orekit
 The original files are distributed under the terms of the Apache 2 license
 which is: Copyright 2010 CS Communication & Systèmes
+
+===============================================================================
+
+The initial code for shuffling an array (originally in class
+"org.apache.commons.math3.random.RandomDataGenerator", now replaced by
+a method in class "org.apache.commons.math3.util.MathArrays") was
+inspired from the algorithm description provided in
+"Algorithms", by Ian Craw and John Pulham (University of Aberdeen 1999).
+The textbook (containing a proof that the shuffle is uniformly random) is
+available here:
+  http://citeseerx.ist.psu.edu/viewdoc/download;?doi=10.1.1.173.1898&rep=rep1&type=pdf
+
+===============================================================================

src/main/java/org/apache/commons/math3/random/RandomDataGenerator.java

@@ -620,11 +620,10 @@ public class RandomDataGenerator implements RandomData, Serializable {
     /**
      * {@inheritDoc}
      *
-     * <p>
-     * Uses a 2-cycle permutation shuffle. The shuffling process is described <a
-     * href="http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node83.html">
-     * here</a>.
-     * </p>
+     * This method calls {@link MathArrays#shuffle(int[],RandomGenerator)
+     * MathArrays.shuffle} in order to create a random shuffle of the set
+     * of natural numbers {@code { 0, 1, ..., n - 1 }}.
+     *
      * @throws NumberIsTooLargeException if {@code k > n}.
      * @throws NotStrictlyPositiveException if {@code k <= 0}.
      */
@@ -649,15 +648,8 @@ public class RandomDataGenerator implements RandomData, Serializable {
     /**
      * {@inheritDoc}
      *
-     * <p>
-     * <strong>Algorithm Description</strong>: Uses a 2-cycle permutation
-     * shuffle to generate a random permutation of <code>c.size()</code> and
-     * then returns the elements whose indexes correspond to the elements of the
-     * generated permutation. This technique is described, and proven to
-     * generate random samples <a
-     * href="http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node83.html">
-     * here</a>
-     * </p>
+     * This method calls {@link #nextPermutation(int,int) nextPermutation(c.size(), k)}
+     * in order to sample the collection.
      */
     public Object[] nextSample(Collection<?> c, int k) throws NumberIsTooLargeException, NotStrictlyPositiveException {
 

src/main/java/org/apache/commons/math3/util/MathArrays.java

@@ -1442,6 +1442,8 @@ public class MathArrays {
      * The {@code start} and {@code pos} parameters select which portion
      * of the array is randomized and which is left untouched.
      *
+     * @see #shuffle(int[],int,Position,RandomGenerator)
+     *
      * @param list Array whose entries will be shuffled (in-place).
      * @param start Index at which shuffling begins.
      * @param pos Shuffling is performed for index positions between
@@ -1455,7 +1457,9 @@ public class MathArrays {
     }
 
     /**
-     * Shuffle the entries of the given array.
+     * Shuffle the entries of the given array, using the
+     * <a href="http://en.wikipedia.org/wiki/Fisher–Yates_shuffle#The_modern_algorithm">
+     * Fisher–Yates</a> algorithm.
      * The {@code start} and {@code pos} parameters select which portion
      * of the array is randomized and which is left untouched.
      *
@@ -1509,6 +1513,8 @@ public class MathArrays {
     /**
      * Shuffle the entries of the given array.
      *
+     * @see #shuffle(int[],int,Position,RandomGenerator)
+     *
      * @param list Array whose entries will be shuffled (in-place).
      * @param rng Random number generator.
      */
@@ -1520,6 +1526,8 @@ public class MathArrays {
     /**
      * Shuffle the entries of the given array.
      *
+     * @see #shuffle(int[],int,Position,RandomGenerator)
+     *
      * @param list Array whose entries will be shuffled (in-place).
      */
     public static void shuffle(int[] list) {