Further review

src/java/org/apache/cassandra/dht/OrderPreservingPartitioner.java

@@ -206,7 +206,7 @@ public long getHeapSize()
         @Override
         public ByteSource asComparableBytes(ByteComparable.Version version)
         {
-            return ByteSource.of((String) token, version);
+            return ByteSource.of(token, version);
         }
     }
 

src/java/org/apache/cassandra/dht/Token.java

@@ -41,16 +41,8 @@ public static abstract class TokenFactory
         public abstract Token fromByteArray(ByteBuffer bytes);
 
         /**
-         * Produce a weakly prefix-free byte-comparable representation of the token, i.e. such a sequence of bytes that any
-         * pair x, y of valid tokens of this type and any bytes b1, b2 between 0x10 and 0xEF,
-         * (+ stands for concatenation)
-         *   compare(x, y) == compareLexicographicallyUnsigned(asByteComparable(x)+b1, asByteComparable(y)+b2)
-         * (i.e. the values compare like the original type, and an added 0x10-0xEF byte at the end does not change that) and:
-         *   asByteComparable(x)+b1 is not a prefix of asByteComparable(y)      (weakly prefix free)
-         * (i.e. a valid representation of a value may be a prefix of another valid representation of a value only if the
-         * following byte in the latter is smaller than 0x10 or larger than 0xEF). These properties are trivially true if
-         * the encoding compares correctly and is prefix free, but also permits a little more freedom that enables somewhat
-         * more efficient encoding of arbitrary-length byte-comparable blobs.
+         * Produce a byte-comparable representation of the token.
+         * See {@link Token#asComparableBytes}
          */
         public ByteSource asComparableBytes(Token token, ByteComparable.Version version)
         {
@@ -65,6 +57,7 @@ public ByteSource asComparableBytes(Token token, ByteComparable.Version version)
          * @return A new {@link Token} instance, corresponding to the given byte-ordered representation. If we were
          * to call {@link #asComparableBytes(ByteComparable.Version)} on the returned object, we should get a
          * {@link ByteSource} equal to the input one as a result.
+         * @throws IllegalArgumentException if the bytes do not encode a valid token.
          */
         public abstract Token fromComparableBytes(ByteSource.Peekable comparableBytes, ByteComparable.Version version);
 

src/java/org/apache/cassandra/utils/bytecomparable/ByteSource.java

@@ -79,7 +79,7 @@ public interface ByteSource
     int EXCLUDED = 0x18;
 
     /**
-     * Reinterprets byte-accessible data as a byte-comparable source that has 0s escaped and finishes in an escaped
+     * Encodes byte-accessible data as a byte-comparable source that has 0s escaped and finishes in an escaped
      * state.
      * This provides a weakly-prefix-free byte-comparable version of the content to use in sequences.
      * (See {@link AbstractEscaper} for a detailed explanation.)
@@ -90,7 +90,7 @@ static <V> ByteSource of(ValueAccessor<V> accessor, V data, Version version)
     }
 
     /**
-     * Reinterprets a byte buffer as a byte-comparable source that has 0s escaped and finishes in an escape.
+     * Encodes a byte buffer as a byte-comparable source that has 0s escaped and finishes in an escape.
      * This provides a weakly-prefix-free byte-comparable version of the content to use in sequences.
      * (See ByteSource.BufferEscaper/Multi for explanation.)
      */
@@ -100,7 +100,7 @@ static ByteSource of(ByteBuffer buf, Version version)
     }
 
     /**
-     * Reinterprets a byte array as a byte-comparable source that has 0s escaped and finishes in an escape.
+     * Encodes a byte array as a byte-comparable source that has 0s escaped and finishes in an escape.
      * This provides a prefix-free byte-comparable version of the content to use in sequences.
      * (See ByteSource.BufferEscaper/Multi for explanation.)
      */
@@ -110,7 +110,7 @@ static ByteSource of(byte[] buf, Version version)
     }
 
     /**
-     * Reinterprets a memory range as a byte-comparable source that has 0s escaped and finishes in an escape.
+     * Encodes a memory range as a byte-comparable source that has 0s escaped and finishes in an escape.
      * This provides a weakly-prefix-free byte-comparable version of the content to use in sequences.
      * (See ByteSource.BufferEscaper/Multi for explanation.)
      */