ESQL: Explain test operators

x-pack/plugin/esql/compute/src/test/java/org/elasticsearch/compute/operator/NullInsertingSourceOperator.java

@@ -24,7 +24,9 @@
 import static org.elasticsearch.test.ESTestCase.between;
 
 /**
- * Inserts nulls into blocks
+ * Inserts "null rows" between incoming rows. By default, a "null row" contains
+ * {@code null} in every {@link Block}. Override {@link #appendNull} to customize
+ * how "null rows" are built.
  */
 public class NullInsertingSourceOperator extends MappingSourceOperator {
     final BlockFactory blockFactory;
@@ -58,6 +60,9 @@ protected Page map(Page page) {
         return result;
     }
 
+    /**
+     * Called on a "null row" to insert values.
+     */
     protected void appendNull(ElementType elementType, Block.Builder builder, int blockId) {
         builder.appendNull();
     }

x-pack/plugin/esql/compute/src/test/java/org/elasticsearch/compute/operator/PositionMergingSourceOperator.java

@@ -18,6 +18,31 @@
 import org.elasticsearch.compute.data.LongBlock;
 import org.elasticsearch.compute.data.Page;
 
+/**
+ * Merges adjacent pairs of positions together into one, block by block.
+ * <p>
+ *     For example:
+ * </p>
+ * <pre>{@code
+ *    a   |   b
+ *  ----- | -----
+ *    1   |   a
+ *    2   |   b
+ *   3, 4 | c, d
+ *   5, 6 | e, f
+ *    7   | null  <---- nulls count as empty lists
+ *   null |   g
+ *    4   |   d   <---- if the input is odd, trailing rows are dropped
+ * }</pre>
+ * becomes
+ * <pre>{@code
+ *       a     |     b
+ *  ---------- | ----------
+ *     1, 2    |   a, b
+ *  3, 4, 5, 6 | c, d, e, f
+ *       7     |     g
+ * }</pre>
+ */
 public class PositionMergingSourceOperator extends MappingSourceOperator {
     final BlockFactory blockFactory;