RFR: JDK-8323760 putIfAbsent documentation conflicts with itself

[Chen Liang]

On Tue, 16 Jan 2024 11:03:28 GMT, John Hendrikx <jhendrikx at openjdk.org> wrote:

>> src/java.base/share/classes/java/util/Map.java line 820:
>> 
>>> 818:      * @param key key with which the specified value is to be associated
>>> 819:      * @param value value to be associated with the specified key
>>> 820:      * @return {@code null} if the specified key was considered absent, else returns
>> 
>> "Considered" feels out of place. No other method in Map uses it. Try to rephrase that sentence or, if it helps, the complete `@return` tag. (@stuart-marks might have more substantial feedback.)
>
> Yeah, I wasn't sure about that, I can make it more specific, I used `considered` here because both unmapped keys and keys mapped to `null` are considered to be absent.

I think `absent or {@code null}` is no less concise yet it is way more accurate than `considered absent`. So something like `@return {@code null} if the mapping for the specified key is absent or has a {@code null} value`?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17438#discussion_r1453427452