minor SpecTest updates

nb-spectest/src/main/java/io/nosqlbench/nb/spectest/core/STBuilder.java

@@ -27,7 +27,7 @@ import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
 
-public abstract class SpecTestBuilder implements STBuilderFacets.All {
+public abstract class STBuilder implements STBuilderFacets.All {
 
     protected List<Path> paths = new ArrayList<>();
     protected List<STPathLoader> scanners  = new ArrayList<>();

nb-spectest/src/main/java/io/nosqlbench/nb/spectest/core/SpecTest.java

@@ -114,7 +114,7 @@ public class SpecTest implements Runnable {
         return new SpecTest.Builder();
     }
 
-    private static class Builder extends SpecTestBuilder {
+    private static class Builder extends STBuilder {
         @Override
         public SpecTest build() {
             return new SpecTest(paths,scanners,validators);

nb-spectest/src/main/java/io/nosqlbench/nb/spectest/package-info.java

@@ -20,6 +20,14 @@
  * of literate programming, but more focused on providing a clearly documented
  * and tested specification, including detailed examples and corner cases.</P>
  *
+ * <H2>Naming</H2>
+ *
+ * <p>
+ * To make navigating and finding relevant classes in this module, except for the
+ * {@link io.nosqlbench.nb.spectest.core.SpecTest} class, which is the main entry point,
+ * all other types are named ST... such as {@link io.nosqlbench.nb.spectest.loaders.STHeadingScanner}.
+ * </p>
+ *
  * <H2>Motivation</H2>
  * <P>There is a common problem in many OSS projects and code bases which has no
  * simple and definitive solution so far: Many APIs, type systems, protocols, and other
@@ -71,5 +79,16 @@
  * </p>
  *
  * <H3>Output Assertions</H3>
+ * For tests which validate correct results based on the full output of some intermediate step, it is
+ * useful to simply use the fenced code blocks to contain some string encoding of the content. This
+ * may be a fully-qualified format wherein all the bland lines and newlines matter. It may be that you
+ * need to read an encoded data structure from yaml or JSON. In these cases, you will generally create
+ * a matching set of these helper types:
+ * <UL>
+ * <LI>A node sequence matcher, which determines what patterns will be extracted from the markdown
+ * files specified to the test harness.</LI>
+ * <LI>A validator which knows how to interpret the resulting node sequences to run a specific type
+ * of validation test.</LI>
+ * </UL>
  */
 package io.nosqlbench.nb.spectest;

nb-spectest/src/main/java/io/nosqlbench/nb/spectest/types/STBuilderFacets.java

@@ -18,7 +18,7 @@ package io.nosqlbench.nb.spectest.types;
 
 import com.vladsch.flexmark.util.ast.Node;
 import io.nosqlbench.nb.spectest.core.SpecTest;
-import io.nosqlbench.nb.spectest.core.SpecTestBuilder;
+import io.nosqlbench.nb.spectest.core.STBuilder;
 import io.nosqlbench.nb.spectest.loaders.STNodePredicate;
 import io.nosqlbench.nb.spectest.loaders.STNodePredicates;
 
@@ -34,7 +34,7 @@ public interface STBuilderFacets {
          * files or other directories. Only files which match a markdown path with a '.md' extension
          * will be validated.
          * @param paths Paths to test
-         * @return this {@link SpecTestBuilder} for method chaining
+         * @return this {@link STBuilder} for method chaining
          */
         WantsPathsOrScannersOrValidators paths(Path... paths);
         /**
@@ -42,7 +42,7 @@ public interface STBuilderFacets {
          * files or other directories. Only files which match a markdown path with a '.md' extension
          * will be validated.
          * @param paths Paths to test
-         * @return this {@link SpecTestBuilder} for method chaining
+         * @return this {@link STBuilder} for method chaining
          */
         default WantsPathsOrScannersOrValidators paths(String... paths) {
             Path[] args = new Path[paths.length];
@@ -56,7 +56,7 @@ public interface STBuilderFacets {
          * files or other directories. Only files which match a markdown path with a '.md' extension
          * will be validated.
          * @param path Paths to test
-         * @return this {@link SpecTestBuilder} for method chaining
+         * @return this {@link STBuilder} for method chaining
          */
         default WantsPathsOrScannersOrValidators path(Path path) {
             return this.paths(path);
@@ -67,7 +67,7 @@ public interface STBuilderFacets {
          * files or other directories. Only files which match a markdown path with a '.md' extension
          * will be validated.
          * @param path Paths to test
-         * @return this {@link SpecTestBuilder} for method chaining
+         * @return this {@link STBuilder} for method chaining
          */
         default WantsPathsOrScannersOrValidators path(String path) {
             return this.paths(Path.of(path));