On Wed, 19 Apr 2023 18:22:28 GMT, Stuart Marks <sma...@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
