KAFKA-15527: Update docs and JavaDocs (#14600)

Part of KIP-985.

Updates JavaDocs for `RangeQuery` and `ReadOnlyKeyValueStore` with regard to ordering guarantees.
Updates Kafka Streams upgrade guide with KIP information.

Reviewer: Matthias J. Sax <matthias@confluent.io>

docs/streams/upgrade-guide.html

@@ -133,6 +133,12 @@
         More details about the new config <code>StreamsConfig#TOPOLOGY_OPTIMIZATION</code> can be found in <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-295%3A+Add+Streams+Configuration+Allowing+for+Optional+Topology+Optimization">KIP-295</a>.
     </p>
 
+    <h3><a id="streams_api_changes_370" href="#streams_api_changes_370">Streams API changes in 3.7.0</a></h3>
+    <p>
+        IQv2 supports <code>RangeQuery</code> that allows to specify unbounded, bounded, or half-open key-ranges, which return data in ascending (byte[]-lexicographical) order (per partition).
+        <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-985%3A+Add+reverseRange+and+reverseAll+query+over+kv-store+in+IQv2">KIP-985</a> extends this functionality by adding <code>.withDescendingKeys()<code> to allow user to receive data in descending order.
+    </p>
+
     <h3><a id="streams_api_changes_360" href="#streams_api_changes_360">Streams API changes in 3.6.0</a></h3>
     <p>
       Rack aware task assignment was introduced in <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-925%3A+Rack+aware+task+assignment+in+Kafka+Streams">KIP-925</a>.

streams/src/main/java/org/apache/kafka/streams/query/RangeQuery.java

@@ -30,7 +30,9 @@ import java.util.Optional;
  * <p>
  *  A range query retrieves a set of records, specified using an upper and/or lower bound on the keys.
  * <p>
- * A scan query retrieves all records contained in the store.
+ *  A scan query retrieves all records contained in the store.
+ * <p>
+ *  Keys' order is based on the serialized byte[] of the keys, not the 'logical' key order.
  * <p>
  */
 @Evolving
@@ -60,7 +62,8 @@ public final class RangeQuery<K, V> implements Query<KeyValueIterator<K, V>> {
     }
 
     /**
-     * Determines if the query keys are in ascending order.
+     * Determines if the serialized byte[] of the keys in ascending order.
+     * Order is based on the serialized byte[] of the keys, not the 'logical' key order.
      * @return true if ascending, false otherwise.
      */
     public boolean isKeyAscending() {
@@ -68,7 +71,8 @@ public final class RangeQuery<K, V> implements Query<KeyValueIterator<K, V>> {
     }
 
     /**
-     * Set the query to return keys in descending order.
+     * Set the query to return the serialized byte[] of the keys in descending order.
+     * Order is based on the serialized byte[] of the keys, not the 'logical' key order.
      * @return a new RangeQuery instance with descending flag set.
      */
     public RangeQuery<K, V> withDescendingKeys() {

streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyKeyValueStore.java

@@ -48,13 +48,13 @@ public interface ReadOnlyKeyValueStore<K, V> {
      * Get an iterator over a given range of keys. This iterator must be closed after use.
      * The returned iterator must be safe from {@link java.util.ConcurrentModificationException}s
      * and must not return null values.
-     * Order is not guaranteed as bytes lexicographical ordering might not represent key order.
+     * Order is based on the serialized byte[] of the keys, not the 'logical' key order.
      *
      * @param from The first key that could be in the range, where iteration starts from.
      *             A null value indicates that the range starts with the first element in the store.
      * @param to   The last key that could be in the range, where iteration ends.
      *             A null value indicates that the range ends with the last element in the store.
-     * @return The iterator for this range, from smallest to largest bytes.
+     * @return The iterator for this range, from key with the smallest bytes to the key with the largest bytes of keys.
      * @throws InvalidStateStoreException if the store is not initialized
      */
     KeyValueIterator<K, V> range(K from, K to);
@@ -63,13 +63,13 @@ public interface ReadOnlyKeyValueStore<K, V> {
      * Get a reverse iterator over a given range of keys. This iterator must be closed after use.
      * The returned iterator must be safe from {@link java.util.ConcurrentModificationException}s
      * and must not return null values.
-     * Order is not guaranteed as bytes lexicographical ordering might not represent key order.
+     * Order is based on the serialized byte[] of the keys, not the 'logical' key order.
      *
      * @param from The first key that could be in the range, where iteration ends.
      *             A null value indicates that the range starts with the first element in the store.
      * @param to   The last key that could be in the range, where iteration starts from.
      *             A null value indicates that the range ends with the last element in the store.
-     * @return The reverse iterator for this range, from largest to smallest key bytes.
+     * @return The iterator for this range, from key with the smallest bytes to the key with the largest bytes of keys.
      * @throws InvalidStateStoreException if the store is not initialized
      */
     default KeyValueIterator<K, V> reverseRange(K from, K to) {