8308694: Clarify reversed() default methods' implementation requirements

Reviewed-by: rriggs

Author: Stuart Marks

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

src/java.base/share/classes/java/util/List.java

@@ -888,8 +888,14 @@ default E removeLast() {
      * {@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

src/java.base/share/classes/java/util/SortedMap.java

@@ -316,8 +316,14 @@ default V putLast(K k, V 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

src/java.base/share/classes/java/util/SortedSet.java

@@ -360,8 +360,14 @@ default E removeLast() {
      * {@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