RFR: 8308694: Clarify reversed() default methods' implementation requirements

[Brent Christian]

On Fri, 16 Jun 2023 15:30:55 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> Can I get a preliminary review of the wording for Deque.reversed()? If the text is good, I'll make corresponding changes to the implSpecs of the other reversed() default methods, namely those in List, SortedMap, and SortedSet and then file the CSR.
>
> src/java.base/share/classes/java/util/Deque.java line 626:
> 
>> 624:      * inverse-ordered method of this Deque. For example, the {@code getFirst}
>> 625:      * method of the returned view delegates to the {@code getLast} method of
>> 626:      * this Deque.
> 
> The description is general and using 'For example" avoids having to be specific about every operation.
> The term "inverse-ordered" is new to this context and perhaps should be "reverse-ordered".
> "inverse" does appear in a few other class descriptions for SequencedXXX but its relation to "reverse" may not be clear.

Rather than describing how the methods delegate, I think we mostly want to say that 
order-sensitive operations are performed in reverse order.

I agree about, "For example", and I would keep the `getFirst` -> `getLast` part - that's a good, straighforward example.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/14504#discussion_r1232571578