Reviewer comments

Author: dorx

mllib/src/main/scala/org/apache/spark/mllib/random/DistributionGenerator.scala

@@ -28,58 +28,49 @@ import org.apache.spark.util.random.{XORShiftRandom, Pseudorandom}
 trait DistributionGenerator extends Pseudorandom with Serializable {
 
   /**
-   * @return An i.i.d sample as a Double from an underlying distribution.
+   * Returns an i.i.d sample as a Double from an underlying distribution.
    */
   def nextValue(): Double
 
   /**
-   * @return A copy of the DistributionGenerator with a new instance of the rng object used in the
-   *         class when applicable. Each partition has a unique seed and therefore requires its
-   *         own instance of the DistributionGenerator.
+   * Returns a copy of the DistributionGenerator with a new instance of the rng object used in the
+   * class when applicable for non-locking concurrent usage.
    */
-  def newInstance(): DistributionGenerator
+  def copy(): DistributionGenerator
 }
 
 /**
  * Generates i.i.d. samples from U[0.0, 1.0]
  */
-class UniformGenerator() extends DistributionGenerator {
+class UniformGenerator extends DistributionGenerator {
 
   // XORShiftRandom for better performance. Thread safety isn't necessary here.
   private val random = new XORShiftRandom()
 
-  /**
-   * @return An i.i.d sample as a Double from U[0.0, 1.0].
-   */
   override def nextValue(): Double = {
     random.nextDouble()
   }
 
-  /** Set random seed. */
   override def setSeed(seed: Long) = random.setSeed(seed)
 
-  override def newInstance(): UniformGenerator = new UniformGenerator()
+  override def copy(): UniformGenerator = new UniformGenerator()
 }
 
 /**
  * Generates i.i.d. samples from the Standard Normal Distribution.
  */
-class StandardNormalGenerator() extends DistributionGenerator {
+class StandardNormalGenerator extends DistributionGenerator {
 
   // XORShiftRandom for better performance. Thread safety isn't necessary here.
   private val random = new XORShiftRandom()
 
-  /**
-   * @return An i.i.d sample as a Double from the Normal distribution.
-   */
   override def nextValue(): Double = {
       random.nextGaussian()
   }
 
-  /** Set random seed. */
   override def setSeed(seed: Long) = random.setSeed(seed)
 
-  override def newInstance(): StandardNormalGenerator = new StandardNormalGenerator()
+  override def copy(): StandardNormalGenerator = new StandardNormalGenerator()
 }
 
 /**
@@ -91,15 +82,11 @@ class PoissonGenerator(val mean: Double) extends DistributionGenerator {
 
   private var rng = new Poisson(mean, new DRand)
 
-  /**
-   * @return An i.i.d sample as a Double from the Poisson distribution.
-   */
   override def nextValue(): Double = rng.nextDouble()
 
-  /** Set random seed. */
   override def setSeed(seed: Long) {
     rng = new Poisson(mean, new DRand(seed.toInt))
   }
 
-  override def newInstance(): PoissonGenerator = new PoissonGenerator(mean)
+  override def copy(): PoissonGenerator = new PoissonGenerator(mean)
 }