RFR: JDK-8323760 putIfAbsent documentation conflicts with itself

[Pavel Rappo]

On Tue, 16 Jan 2024 07:40:44 GMT, John Hendrikx <jhendrikx 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.)

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

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