update docs for op types

adapters-api/src/main/java/io/nosqlbench/engine/api/activityimpl/uniform/flowtypes/ChainingOp.java

@@ -19,16 +19,25 @@ package io.nosqlbench.engine.api.activityimpl.uniform.flowtypes;
 import java.util.function.Function;
 
 /**
- * Run a function on the current cached result and replace it
- * with the result of the function. Functions are one way of invoking
+ * <H2>ChainingOp<I,O>: f(I) -> O</I,O></H2>
+ * <P>
+ * Run a function on the current cached result in the current thread and replace it
+ * with the result of the function. ChainingOps are one way of invoking
  * logic within a cycle. However, they are not intended to stand alone.
- * A CycleFunction must always have an input to work on. This input is
- * provided by a Supplier as optionally implemented by an Op
+ * A ChainingOp must always have an input to work on,
+ * provided by either a {@link CycleOp} OR <em>another</em> call to a {@link ChainingOp}</P>
  *
- * @param <I> Some input type.
+ * @param <I> Some input type, as determined by a previous {@link CycleOp} or {@link ChainingOp} on the same thread.
  * @param <O> Some output type.
  */
-public interface ChainingOp<I,O> extends Op, Function<I,O> {
+public interface ChainingOp<I, O> extends Op, Function<I, O> {
+
+    /**
+     * Transform a value from a previous action and provide the result for a subsequent action.
+     *
+     * @param lastResult object form a previous operation or action
+     * @return a new result
+     */
     @Override
-    O apply(I i);
+    O apply(I lastResult);
 }

adapters-api/src/main/java/io/nosqlbench/engine/api/activityimpl/uniform/flowtypes/CycleOp.java

@@ -19,32 +19,33 @@ package io.nosqlbench.engine.api.activityimpl.uniform.flowtypes;
 import java.util.function.LongFunction;
 
 /**
- * A CycleRunnable is simply a variation of a Runnable type.
- * The main difference is that it is supplied with the cycle
- * as input.
+ * <H2>CycleOp: f(cycle) -> T</H2>
+ * <p>A CycleOp of T is an operation which takes a long input value
+ * and produces a value of type T. It is implemented as
+ * {@link LongFunction} of T.</p>
+ *
+ * <P>This variant of {@link Op} has the ability to see the cycle
+ * which was previously used to select the op implementation.</p>
+ *
+ * <p>It also has the ability to emit an value which can be seen a subsequent operation, if
+ * and only if it is a {@link ChainingOp}s.</P>
+ *
+ * <h2>Designer Notes</h2>
+ * <p>
+ * If you are using the value in this call to select a specific type of behavior, it is very
+ * likely a candidate for factoring into separate op implementations.
+ * The {@link io.nosqlbench.engine.api.activityimpl.OpMapper}
+ * and {@link io.nosqlbench.engine.api.activityimpl.OpDispenser} abstractions are meant to move
+ * op type selection and scheduling to earlier in the activity.
+ * </p>
+ *
  */
 public interface CycleOp<T> extends Op, LongFunction<T> {
-//    /**
-//     * <p>Run an action for the given cycle. The cycle is provided for anecdotal
-//     * usage such as logging and debugging. It is valid to use the cycle value in these places,
-//     * but you should not use it to determine the logic of what is run. The mechanism
-//     * for doing this is provided in {@link io.nosqlbench.engine.api.activityimpl.OpMapper}
-//     * and {@link io.nosqlbench.engine.api.activityimpl.OpDispenser} types.</p>
-//     *
-//     *
-//     * @param cycle The cycle value for which an operation is run
-//     */
-////     * This method should do the same thing that {@link #apply(long)} does, except that
-////     * there is no need to prepare or return a result. This is the form that will be called
-////     * if there is no chaining operation to consume the result of this operation.
-//    void accept(long cycle);
-
     /**
-     * <p>Run an action for the given cycle. The cycle
-     * value is only to be used for anecdotal presentation. This form is called
-     * when there is a chaining operation which will do something with this result.</p>
+     * <p>Run an action for the given cycle.</p>
+     *
      * @param value The cycle value for which an operation is run
-     * @return A result which is the native result type for the underlying driver.
+     * @return A result object which <em>may</em> be used by a subsequent {@link ChainingOp}
      */
     @Override
     T apply(long value);

adapters-api/src/main/java/io/nosqlbench/engine/api/activityimpl/uniform/flowtypes/Op.java

@@ -17,21 +17,20 @@
 package io.nosqlbench.engine.api.activityimpl.uniform.flowtypes;
 
 /**
- * This is the root type of any operation which is used in a NoSQLBench
+ * <p>This is the root type of any operation which is used in a NoSQLBench
  * DriverAdapter. It is a tagging interface for incremental type validation
- * in the NB runtime. You probably don't want to use it directly.
+ * in the NB runtime. You probably don't want to use it directly.</p>
  *
- * Instead, use these:
+ * <p>Instead, use <em>one</em> of these:
  * <ul>
  *  <li>{@link CycleOp}</li> - An interface that will called if there is nothing to consume
  *  the result type from your operation. In some cases preparing a result body to
- *  hand down the chain is more costly, so implementing this interface allows ...
+ *  hand down the chain is more costly, so implementing this interface allows the runtime
+ *  to be more optimized.</li>
+ *  <li>{@link ChainingOp}</li>
  * </ul>
- *
- * either {@link CycleOp} or {@link ChainingOp} (but not both!)
- *
- * In the standard flow of an activity, either of the above interfaces is called
- * so long as an Op implements one of them.
+ * </p>
  */
+// TODO: optimize the runtime around the specific op type
 public interface Op extends OpResultSize {
 }

adapters-api/src/main/java/io/nosqlbench/engine/api/activityimpl/uniform/flowtypes/RunnableOp.java

@@ -16,5 +16,19 @@
 
 package io.nosqlbench.engine.api.activityimpl.uniform.flowtypes;
 
+/**
+ * <H2>RunnableOp</H2>
+ * <P>This is the simplest form of an executable operation in NoSQLBench.
+ * It is simply an operation is run for side-effect only.</P>
+ */
 public interface RunnableOp extends Op, Runnable {
+
+    /**
+     * Invoke the operation. If you need to see the value of the current
+     * cycle, then you can use {@link CycleOp} instead. If you need to
+     * use a cached result of a previous operation, then you may need to
+     * use {@link ChainingOp}.
+     */
+    @Override
+    void run();
 }