Index: src/main/java/java/util/Random.java =================================================================== --- src/main/java/java/util/Random.java (revision 544772) +++ src/main/java/java/util/Random.java (working copy) @@ -77,12 +77,14 @@ } /** - * Answers a pseudo-random uniformly distributed int value of - * the number of bits specified by the argument bits as - * described by Donald E. Knuth in The Art of Computer Programming, - * Volume 2: Seminumerical Algorithms, section 3.2.1. + * Returns a pseudo-random uniformly distributed int value of + * the number of bits specified by the argument bits. + * + * Implements D. H. Lehmer's random number algorithm found in The Art of + * Computer Programming, Volume 2: Seminumerical Algorithms, by Donald + * E. Knuth (section 3.2.1). * - * @return int a pseudo-random generated int number + * @return a pseudo-randomly generated int * @param bits * number of bits of the returned value * @@ -136,7 +138,7 @@ * Generates a normally distributed random double number between 0.0 * inclusively and 1.0 exclusively. * - * @return double + * @return a random double between 0.0 and 1.0 * * @see #nextFloat */ @@ -148,7 +150,7 @@ * Generates a normally distributed random float number between 0.0 * inclusively and 1.0 exclusively. * - * @return float a random float number between 0.0 and 1.0 + * @return a random float between 0.0 and 1.0 * * @see #nextDouble */ @@ -157,14 +159,15 @@ } /** - * pseudo-randomly generates (approximately) a normally distributed + * Returns a pseudo-randomly generated, normally distributed * double value with mean 0.0 and a standard deviation value - * of 1.0 using the polar method of G. E. P. Box, M. - * E. Muller, and G. Marsaglia, as described by Donald E. Knuth in The - * Art of Computer Programming, Volume 2: Seminumerical Algorithms, - * section 3.4.1, subsection C, algorithm P + * of 1.0. * - * @return double + * Implements G. E. P. Box, M. E. Muller, and G. Marsaglia's polar method + * found in The Art of Computer Programming, Volume 2: Seminumerical + * Algorithms, by Donald E. Knuth (section 3.4.1). + * + * @return a pseudo-randomly generated double * * @see #nextDouble */ @@ -194,7 +197,7 @@ * Generates a uniformly distributed 32-bit int value from * the this random number sequence. * - * @return int uniformly distributed int value + * @return a randomly generated int * * @see java.lang.Integer#MAX_VALUE * @see java.lang.Integer#MIN_VALUE @@ -206,13 +209,12 @@ } /** - * Returns to the caller a new pseudo-random integer value which is uniformly - * distributed between 0 (inclusively) and the value of n - * (exclusively). + * Returns a new pseudo-random integer value which is uniformly distributed + * between 0 (inclusively) and n (exclusively). * - * @return int + * @return a randomly generated int between 0 and n * @param n - * int + * the upper limit of the values that can be returned */ public int nextInt(int n) { if (n > 0) { @@ -246,8 +248,9 @@ } /** - * Modifies the seed using linear congruential formula presented in The - * Art of Computer Programming, Volume 2, Section 3.2.1. + * Modifies the seed using a linear congruential formula, as found in The + * Art of Computer Programming, Volume 2, by Donald E. Knuth (section + * 3.2.1). * * @param seed * the seed that alters the state of the random number generator