On Tue, 16 Jan 2024 10:41:04 GMT, Pavel Rappo <[email protected]> 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
