added comment and todo

test/distributed/org/apache/cassandra/distributed/test/cql3/SingleNodeTableWalkTest.java

@@ -73,6 +73,7 @@
 import static org.apache.cassandra.utils.AbstractTypeGenerators.getTypeSupport;
 import static org.apache.cassandra.utils.Generators.toGen;
 
+//TODO (coverage): add partition restricted clustering range queries: eg. WHERE pk=? and ck BETWEEN ? AND ?
 public class SingleNodeTableWalkTest extends StatefulASTBase
 {
     private static final Logger logger = LoggerFactory.getLogger(SingleNodeTableWalkTest.class);

test/harry/main/org/apache/cassandra/harry/model/BytesPartitionState.java

@@ -288,6 +288,7 @@ public static class Ref implements Comparable<Ref>
         @Nullable
         public final Clustering<ByteBuffer> key;
         public final Token token;
+        // when true (null, token) > (key, token).  When false (null, token) < (key, token)
         private final boolean nullKeyGtMatchingToken;
 
         private Ref(Factory factory, Clustering<ByteBuffer> key, Token token)
@@ -492,6 +493,12 @@ public BytesPartitionState.Ref createRef(Clustering<ByteBuffer> key)
             return new Ref(this, key, token);
         }
 
+        /**
+         * Define a ref where the {@link Ref#key} is {@code null}, and the ordering of this ref is that (null, token) is either before (key, token) or after; depending on {@code nullKeyGtMatchingToken}
+         *
+         * @param token for the ref
+         * @param nullKeyGtMatchingToken when true (null, token) > (key, token).  When false (null, token) < (key, token)
+         */
         public BytesPartitionState.Ref createRef(Token token, boolean nullKeyGtMatchingToken)
         {
             return new BytesPartitionState.Ref(this, token, nullKeyGtMatchingToken);