On Tue, 16 Jan 2024 07:40:44 GMT, John Hendrikx <jhendr...@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.)
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/17438#discussion_r1453244818
