From f82c8184b26142da4018ae096cfa39d87a4c6540 Mon Sep 17 00:00:00 2001
From: Stuart Marks <smarks@openjdk.org>
Date: Wed, 12 Jul 2023 16:10:41 +0000
Subject: [PATCH] 8308694: Clarify reversed() default methods' implementation
 requirements

Reviewed-by: rriggs
---
 src/java.base/share/classes/java/util/Deque.java     | 10 ++++++++--
 src/java.base/share/classes/java/util/List.java      | 10 ++++++++--
 src/java.base/share/classes/java/util/SortedMap.java | 10 ++++++++--
 src/java.base/share/classes/java/util/SortedSet.java | 10 ++++++++--
 4 files changed, 32 insertions(+), 8 deletions(-)

diff --git a/src/java.base/share/classes/java/util/Deque.java b/src/java.base/share/classes/java/util/Deque.java
index 13a2e150d97..fd42bc356de 100644
--- a/src/java.base/share/classes/java/util/Deque.java
+++ b/src/java.base/share/classes/java/util/Deque.java
@@ -617,8 +617,14 @@ public interface Deque<E> extends Queue<E>, SequencedCollection<E> {
      * {@inheritDoc}
      *
      * @implSpec
-     * The implementation in this interface returns an instance of a reverse-ordered
-     * Deque that delegates its operations to this Deque.
+     * The implementation in this interface returns a reverse-ordered Deque
+     * view. The {@code reversed()} method of the view returns a reference
+     * to this Deque. Other operations on the view are implemented via calls to
+     * public methods on this Deque. The exact relationship between calls on the
+     * view and calls on this Deque is unspecified. However, order-sensitive
+     * operations generally delegate to the appropriate method with the opposite
+     * orientation. For example, calling {@code getFirst} on the view results in
+     * a call to {@code getLast} on this Deque.
      *
      * @return a reverse-ordered view of this collection, as a {@code Deque}
      * @since 21
diff --git a/src/java.base/share/classes/java/util/List.java b/src/java.base/share/classes/java/util/List.java
index e9576455ca7..17cf635aa7a 100644
--- a/src/java.base/share/classes/java/util/List.java
+++ b/src/java.base/share/classes/java/util/List.java
@@ -888,8 +888,14 @@ public interface List<E> extends SequencedCollection<E> {
      * {@inheritDoc}
      *
      * @implSpec
-     * The implementation in this interface returns an instance of a reverse-ordered
-     * List that delegates its operations to this List.
+     * The implementation in this interface returns a reverse-ordered List
+     * view. The {@code reversed()} method of the view returns a reference
+     * to this List. Other operations on the view are implemented via calls to
+     * public methods on this List. The exact relationship between calls on the
+     * view and calls on this List is unspecified. However, order-sensitive
+     * operations generally delegate to the appropriate method with the opposite
+     * orientation. For example, calling {@code getFirst} on the view results in
+     * a call to {@code getLast} on this List.
      *
      * @return a reverse-ordered view of this collection, as a {@code List}
      * @since 21
diff --git a/src/java.base/share/classes/java/util/SortedMap.java b/src/java.base/share/classes/java/util/SortedMap.java
index 1af9d59e83e..447b0a2c7e7 100644
--- a/src/java.base/share/classes/java/util/SortedMap.java
+++ b/src/java.base/share/classes/java/util/SortedMap.java
@@ -316,8 +316,14 @@ public interface SortedMap<K,V> extends SequencedMap<K,V> {
      * {@inheritDoc}
      *
      * @implSpec
-     * The implementation in this interface returns an instance of a reverse-ordered
-     * SortedMap that delegates its operations to this SortedMap.
+     * The implementation in this interface returns a reverse-ordered SortedMap
+     * view. The {@code reversed()} method of the view returns a reference
+     * to this SortedMap. Other operations on the view are implemented via calls to
+     * public methods on this SortedMap. The exact relationship between calls on the
+     * view and calls on this SortedMap is unspecified. However, order-sensitive
+     * operations generally delegate to the appropriate method with the opposite
+     * orientation. For example, calling {@code firstEntry} on the view results in
+     * a call to {@code lastEntry} on this SortedMap.
      *
      * @return a reverse-ordered view of this map, as a {@code SortedMap}
      * @since 21
diff --git a/src/java.base/share/classes/java/util/SortedSet.java b/src/java.base/share/classes/java/util/SortedSet.java
index 48473a1fed5..3b4612457c6 100644
--- a/src/java.base/share/classes/java/util/SortedSet.java
+++ b/src/java.base/share/classes/java/util/SortedSet.java
@@ -360,8 +360,14 @@ public interface SortedSet<E> extends Set<E>, SequencedSet<E> {
      * {@inheritDoc}
      *
      * @implSpec
-     * The implementation in this interface returns an instance of a reverse-ordered
-     * SortedSet that delegates its operations to this SortedSet.
+     * The implementation in this interface returns a reverse-ordered SortedSet
+     * view. The {@code reversed()} method of the view returns a reference
+     * to this SortedSet. Other operations on the view are implemented via calls to
+     * public methods on this SortedSet. The exact relationship between calls on the
+     * view and calls on this SortedSet is unspecified. However, order-sensitive
+     * operations generally delegate to the appropriate method with the opposite
+     * orientation. For example, calling {@code getFirst} on the view results in
+     * a call to {@code getLast} on this SortedSet.
      *
      * @return a reverse-ordered view of this collection, as a {@code SortedSet}
      * @since 21