Addresses PR comments

partiql-spi/src/main/java/org/partiql/eval/value/Datum.java

@@ -655,18 +655,40 @@ static Datum struct(@NotNull Iterable<Field> values) {
     }
 
     /**
-     * Comparator for PartiQL's scalar comparison operator.
+     * Comparator for PartiQL values.
+     * <p>
+     * This may be used for the comparison operators, GROUP BY, ORDER BY, and DISTINCT. The conventional use
+     * of {@link java.util.HashMap}, {@link java.util.HashSet}, {@link Object#hashCode()}, and
+     * {@link Object#equals(Object)} will not work outright with Datum to implement the before-mentioned operations due
+     * to requirements by the PartiQL and SQL Specifications. One may use {@link java.util.TreeMap} and
+     * {@link java.util.TreeSet} in combination with this {@link Comparator} to implement the before-mentioned
+     * operations.
+     * </p>
      * @return the default comparator for {@link Datum}. The comparator orders null values first.
+     * @see Datum
+     * @see java.util.TreeSet
+     * @see java.util.TreeMap
      */
     @NotNull
     static Comparator<Datum> comparator() {
         return comparator(true);
     }
 
     /**
-     * Comparator for PartiQL's scalar comparison operator.
+     * Comparator for PartiQL values.
+     * <p>
+     * This may be used for the comparison operators, GROUP BY, ORDER BY, and DISTINCT. The conventional use
+     * of {@link java.util.HashMap}, {@link java.util.HashSet}, {@link Object#hashCode()}, and
+     * {@link Object#equals(Object)} will not work outright with Datum to implement the before-mentioned operations due
+     * to requirements by the PartiQL and SQL Specifications. One may use {@link java.util.TreeMap} and
+     * {@link java.util.TreeSet} in combination with this {@link Comparator} to implement the before-mentioned
+     * operations.
+     * </p>
      * @param nullsFirst if true, nulls are ordered before non-null values, otherwise after.
      * @return the default comparator for {@link Datum}.
+     * @see Datum
+     * @see java.util.TreeSet
+     * @see java.util.TreeMap
      */
     @NotNull
     static Comparator<Datum> comparator(boolean nullsFirst) {

partiql-spi/src/main/java/org/partiql/eval/value/DatumComparator.java

@@ -34,11 +34,13 @@ abstract class DatumComparator implements Comparator<Datum> {
     private static final int TYPE_KINDS_LENGTH = TYPE_KINDS.length;
 
     /**
-     * This array defines the precedence of types when comparing values of different types.
-     * The lower the index, the higher the precedence. However, this is used for generating the BASELINE precedence.
-     * This may be overridden by families of types. For example, all number values are compared by their mathematical
-     * representation (not their {@link PType.Kind}. Therefore, when comparing two numbers of different types, this
-     * precedence array will not be used.
+     * This array defines the precedence of type families when comparing values of different types. The lower the index,
+     * the higher the precedence. Please see
+     * <a href="https://partiql.org/partiql-lang/#sec:order-by-less-than">PartiQL Specification Section 12.2</a> for
+     * more information.
+     * <p>
+     * This is only used for aiding in the initialization of the {@link #COMPARISON_TABLE}.
+     * </p>
      */
     @NotNull
     private static final Map<PType.Kind, Integer> TYPE_PRECEDENCE = initializeTypePrecedence();
@@ -180,6 +182,18 @@ private static Map<PType.Kind, Integer> initializeTypePrecedence() {
         return precedence;
     }
 
+    /**
+     * This essentially operates in two passes.
+     * <ol>
+     * <li>Initialize the comparisons for the cartesian product of all type kinds based solely on
+     * the {@link #TYPE_PRECEDENCE}.</li>
+     * <li>Rewrite the comparisons where the values themselves will need to be compared. For example, all PartiQL numbers
+     * need to have their JVM primitives extracted before making comparison judgements.</li>
+     * </ol>
+     * @return the 2D comparison table
+     * @see #initializeComparatorArray(PType.Kind)
+     * @see #fillIntComparator(DatumComparison[])
+     */
     @SuppressWarnings("deprecation")
     private static DatumComparison[][] initializeComparators() {
         // Initialize Table

partiql-spi/src/main/kotlin/org/partiql/value/PartiQLValue.kt

@@ -85,6 +85,7 @@ public sealed interface PartiQLValue {
          */
         @JvmStatic
         @JvmOverloads
+        @Deprecated("This will be removed in a future major-version release.")
         public fun comparator(nullsFirst: Boolean = true): Comparator<PartiQLValue> = PartiQLValueComparatorInternal(nullsFirst)
     }
 }