RFR: JDK-8323760 putIfAbsent documentation conflicts with itself

[John Hendrikx]

On Tue, 16 Jan 2024 10:41:04 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Update the documentation for `@return` tag of `putIfAbsent` to match the main description. `putIfAbsent` uses the same wording as `put` for its `@return` tag, but that is incorrect.  `putIfAbsent` never returns the **previous** value, as the whole point of the method is not the replace the value if it was present.  As such, if it returns a value, it is the **current** value, and in all other cases it will return `null`.
>
> 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 and key maps to `null` is considered to be absent.

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

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