typos and minor fixes

adapter-cqld4/src/main/java/io/nosqlbench/adapter/cqld4/opmappers/GremlinOpDispenser.java

@@ -40,21 +40,8 @@ public class GremlinOpDispenser extends BaseOpDispenser<Cqld4ScriptGraphOp> {
 
         LongFunction<ScriptGraphStatementBuilder> finalFunc = func;
         this.stmtFunc = l -> finalFunc.apply(l).build();
-//        LongFunction<SimpleGraphStatement> gsFunc = l -> finalFunc.apply(l).build();
-//
-//        this.stmtFunc = gsFunc;
-//        // graph-internal-options
-//        Optional<LongFunction<Map>> internalOptionsFunc = cmd.getAsOptionalFunction("graph-internal-options", Map.class);
-//        if (internalOptionsFunc.isPresent()) {
-//            LongFunction<ScriptGraphStatementBuilder> finalFunc = func;
-//            LongFunction<Map> optionsFunc = internalOptionsFunc.get();
-//            func = l -> {
-//                GraphStatement gs = gsFunc.apply(l);
-//                Map options = optionsFunc.apply(l);
-//                options.forEach((k,v) -> gs.s);
-//
-//            }
-//        }
+
+        // TODO: investigate enabling equivalent settings in core graph
         /**
          *            gs.setGraphInternalOption("cfg.external_vertex_verify",String.valueOf(verifyVertexIds));
          *             gs.setGraphInternalOption("cfg.verify_unique",String.valueOf(java.lang.Boolean.FALSE));

adapters-api/src/main/java/io/nosqlbench/engine/api/activityimpl/OpDispenser.java

@@ -18,13 +18,13 @@ import java.util.function.LongFunction;
  * implementing op dispensers.
  * <p>
  * <H2>Concepts</H2>
- * Op Synthesis is the process of building a specific and executable
+ * Op Synthesis is the process of building a specific executable
  * operation for some (low level driver) API by combining the
  * static and dynamic elements of the operation together.
  * In most cases, implementations of OpDispenser will be constructed
  * within the logic of an {@link OpMapper} which is responsible for
  * determining the type of OpDispenser to use as associated with a specific
- * type {@code (<T>)}. The OpMapper is called for each type of operation
+ * type &lt;T&gt;. The OpMapper is called for each type of operation
  * that is active during activity initialization. It's primary responsibility
  * is figuring out what types of {@link OpDispenser}s to create based
  * on the op templates provided by users. Once the activity is initialized,
@@ -36,7 +36,7 @@ import java.util.function.LongFunction;
  * <h2>Implementation Strategy</h2>
  * <p>OpDispenser implementations are intended to be implemented
  * for each type of distinct operation that is supported by a
- * {@link io.nosqlbench.engine.api.activityimpl.uniform.DriverAdapter}.
+ * DriverAdapter.
  * That is not to say that an OpDispenser can't be responsible for
  * producing multiple types of operations. Operations which are similar
  * in what they need and how they are constructed make sense to be implemented

nb-api/src/main/java/io/nosqlbench/nb/api/config/params/NBParams.java

@@ -33,7 +33,7 @@ import java.util.stream.Collectors;
  * <p>If an element contains a property named <i>name</i>, then the value of this property
  * is taken as the name of the element. This is useful in certain contexts when you
  * need to define a name at the source of a configuration element but expose it
- * to readers. This means that an element can be positioned with a hierarchic structure
+ * to readers. This means that an element can be positioned within a hierarchic structure
  * simply by naming it appropriately.</p>
  * <hr/>
  *
@@ -61,7 +61,7 @@ import java.util.stream.Collectors;
  *
  * <H2>Single-Element View</H2>
  *
- * <p>The <i>one element access</i> interface is mean to provide basic support for
+ * <p>The <i>one element access</i> interface is meant to provide basic support for
  * parameterizing a single entity. The names of the parameters surfaced at the
  * top level should map directly to the names of properties as provided by the
  * underlying data source. This is irrespective of whatever other structure may
@@ -69,11 +69,26 @@ import java.util.stream.Collectors;
  * names of the configuration object are available under the same top-level names
  * within the one element interface.</p>
  * <br/>
- * <p>As data sources can provide either one or many style results, it is important
- * that each data source provide a clear explanation about how it distinguishes
- * reading a single element vs reading (possibly) multiple elements.</p>
+ *
+ * <H2>Avoiding Ambiguity</H2>
+ * <p>As data sources may provide either one or many style results, and the consumption
+ * patterns of these are different, a distinction must be made by each data source
+ * that is faithful to users' expectations. In other words, it must be clear to users
+ * when a single entity is being configured and when multiple entities are being configured.
+ * Take for example, configuration of a single user's preferences. In this case, you would have
+ * a set of preferences each with a name. The user providing the configuration values <EM>AND</EM>
+ * the developer who writes code to consume these values must both agree that they are configuring
+ * <EM>A set of named preference values for a single user entity.</EM> However, if you were intending
+ * to read the configuration values for a set of users, each with their own set of configuration values,
+ * then as before, it must be clear to the user providing the values as well as the developer writing
+ * code to consume these values that they are communicating <em>A set of user preferences objects,
+ * each consisting of a set of named user preference values.</em>. If the programmer were to read a
+ * single preference object as a set of preferences for many users, a logical error would occur, at least.
+ * Likewise, reading a named set of preferences objects as a single preference object would cause a logical
+ * error.</p>
+ *
  * <br/>
- * <p>When explicitly reading a single element, the underlying data source must provide
+ * <p>When explicitly reading a configuration source as a single element, the underlying data source must provide
  * exactly one element <EM>OR</EM> provide a series of elements of which some contain
  * <i>name</i> properties. Non-distinct names are allowed, although the last element
  * for a given name will be the only one visible to readers. It is an error for the