[commons-rng] branch master updated: Update JMH javadocs with notes on how to add new generators.

[aherbert]

This is an automated email from the ASF dual-hosted git repository.

aherbert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-rng.git


The following commit(s) were added to refs/heads/master by this push:
     new e463f5b  Update JMH javadocs with notes on how to add new generators.
e463f5b is described below

commit e463f5b51702efbec61d6bcbe7cdafa4fa1d988f
Author: aherbert <aherb...@apache.org>
AuthorDate: Wed Apr 10 11:26:13 2019 +0100

    Update JMH javadocs with notes on how to add new generators.
---
 .../commons/rng/examples/jmh/BaselineSources.java  | 24 +++++++++++++++++++---
 .../commons/rng/examples/jmh/RandomSources.java    |  3 ++-
 .../commons/rng/examples/jmh/package-info.java     | 14 ++++++++++++-
 3 files changed, 36 insertions(+), 5 deletions(-)

diff --git 
a/commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh/BaselineSources.java
 
b/commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh/BaselineSources.java
index 1659fea..b3cbcab 100644
--- 
a/commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh/BaselineSources.java
+++ 
b/commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh/BaselineSources.java
@@ -26,10 +26,28 @@ import org.openjdk.jmh.annotations.Setup;
 import org.openjdk.jmh.annotations.State;
 
 /**
- * Defines the benchmark state to retrieve the various "RandomSource"s.
+ * A benchmark state that can retrieve the various generators defined by 
{@link RandomSource}
+ * values.
  *
- * <p>A baseline implementation for the {@link UniformRandomProvider} must be 
provided by
- * implementing classes.</p>
+ * <p>The state will include only those that do not require additional 
constructor arguments.</p>
+ *
+ * <p>This class is abstract since it adds a special {@code RandomSource} named
+ * {@code BASELINE}. A baseline implementation for the {@link 
UniformRandomProvider}
+ * interface must be provided by implementing classes. For example to baseline 
methods
+ * using {@link UniformRandomProvider#nextInt()} use the following code:</p>
+ *
+ * <pre>
+ * &#64;State(Scope.Benchmark)
+ * public static class Sources extends BaselineSources {
+ *     &#64;Override
+ *     protected UniformRandomProvider createBaseline() {
+ *         return BaselineUtils.getNextInt();
+ *     }
+ * }
+ * </pre>
+ *
+ * <p>Note: It is left to the implementation to ensure the baseline is 
suitable for the method
+ * being tested.</p>
  */
 @State(Scope.Benchmark)
 public abstract class BaselineSources {
diff --git 
a/commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh/RandomSources.java
 
b/commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh/RandomSources.java
index b8258ee..765a448 100644
--- 
a/commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh/RandomSources.java
+++ 
b/commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh/RandomSources.java
@@ -24,7 +24,8 @@ import org.openjdk.jmh.annotations.Setup;
 import org.openjdk.jmh.annotations.State;
 
 /**
- * A benchmark state that can retrieve the various {@link RandomSource} 
generators.
+ * A benchmark state that can retrieve the various generators defined by 
{@link RandomSource}
+ * values.
  *
  * <p>The state will include only those that do not require additional 
constructor arguments.</p>
  */
diff --git 
a/commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh/package-info.java
 
b/commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh/package-info.java
index f6a9ab7..b8f1645 100644
--- 
a/commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh/package-info.java
+++ 
b/commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh/package-info.java
@@ -22,6 +22,18 @@
  * This package contains code to perform a
  * <a href="http://openjdk.java.net/projects/code-tools/jmh";>JMH</a> run.
  * </p>
+ *
+ * <p>
+ * Support for a new {@link org.apache.commons.rng.UniformRandomProvider 
UniformRandomProvider}
+ * with a defined enum value in {@link 
org.apache.commons.rng.simple.RandomSource RandomSource}
+ * can be added by updating:
+ * </p>
+ *
+ * <ul>
+ *   <li>The {@link org.apache.commons.rng.examples.jmh.RandomSourceValues 
RandomSourceValues} class
+ *   <li>The {@link org.apache.commons.rng.examples.jmh.BaselineSources 
BaselineSources} class
+ *   <li>The {@link org.apache.commons.rng.examples.jmh.ConstructionPerformance
+ *       ConstructionPerformance} class
+ * </ul>
  */
-
 package org.apache.commons.rng.examples.jmh;