Summary
-------

Clarify the implementation requirements (`@implSpec` sections) of the specifications of the `reversed`
methods of `Deque`, `List`, `SortedMap`, and `SortedSet`. This request is for JDK 21 and 22.

Problem
-------

The current implementation requirements merely say that the returned reverse-ordered view delegates
its operations to the backing collection. This seems to imply that calling `foo` on the view results in a call
to `foo` on the underlying collection. This isn't correct, of course (since the view is reversed, after all) but
it needs to be clarified.


Solution
--------

The obvious revision is to specify that a call to a method on the view results in a call to the appropriate
method of the backing collection, but with the opposite orientation. This is true, but only for some methods.
For example, a call to `getFirst` on the view results in a call to `getLast` on the backing collection. However,
this isn't true for all methods. For example, calling `reversed` on the view simply returns the backing
collection. This ought to be specified.

Other methods, however, cannot be specified so simply. For example, consider `addAll`. This takes all
the elements from its argument collection, in encounter order, and adds them at the end of the encounter
order of the receiver. If called on a reversed view, it needs to take the elements from the argument collection
in *reverse encounter order* and add them at the *front* of the backing collection. There are many different
ways to do this, and we don't want to specify any particular way. This is true of many of the complex
collection operations, such as `spliterator`. For these operations, we require only that the default
implementation result in calls to public methods on the backing collection, but we also state that the
exact behaviors in calling those public methods is unspecified.

Specification
-------------

Deque.reversed() --


          * @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


List.reversed() --


          * @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


SortedMap.reversed() --

          * @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


SortedSet.reversed() --


          * @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