RFR: 8266571: Sequenced Collections [v7]

[Nir Lisker]

On Wed, 19 Apr 2023 18:22:28 GMT, Stuart Marks <smarks at openjdk.org> wrote:

>> src/java.base/share/classes/java/util/SequencedMap.java line 110:
>> 
>>> 108:  * {@code Entry} thus obtained will update a mapping in the underlying map, or whether
>>> 109:  * it will throw an exception, or whether changes to the underlying map are visible in
>>> 110:  * that {@code Entry}.
>> 
>> These 3 paragraphs all talk about `Entry`s' connection to the map. I think that they can be reconciled by explicitly noting each way to get an entry and the conditions that apply on it. In broad strokes:
>> 
>>> `{@link Map.Entry}` instances can be obtained in several ways.
>>> By iterating the `{@link #entrySet}` view... These entries maintain a connection...
>>> By calling the `{@link #firstEntry}`... methods. These entries represent snapshots of...
>>> By other means, such as from methods of views of the map (`sequencedMap.sequencedEntrySet().getFirst();`). These entries entries might or might not be connected...
>
> Not sure what you're suggesting here. There are indeed different ways to obtain entries, but they can't be reconciled because the spec imposes different requirements (or explicitly leaves things unspecified) on entries obtained by different means.

What I'm suggesting is this: these 3 paragraphs read like a mini-section about entries. I think that if a sentence is added at their beginning, like 

> `{@link Map.Entry}` instances can be obtained in several/the following ways."

and/or if the language used in them was more consistent, like

> Entries obtained by <method of obtaining> are <requirements>

then it will make this part of the docs easier to follow. More concretely, if the first paragraph uses the language

> The `{@link Map.Entry}` instances obtained by iterating the `{@link #entrySet}` view...

then the second could use

> The `{@code Map.Entry}` instances obtained by the methods `{@link #firstEntry}`...

and the third

> The `{@code Entry}` instances obtained by other means...

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

PR Review Comment: https://git.openjdk.org/jdk/pull/7387#discussion_r1172484646