RFR: JDK-8323760 putIfAbsent documentation conflicts with itself [v2]

[Stuart Marks]

On Tue, 13 Feb 2024 17:11:05 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`.
>
> John Hendrikx has updated the pull request incrementally with four additional commits since the last revision:
> 
>  - Add code block around argument
>  - Reword
>  - Reword to use put's previous value wording
>  - Reword more clearly

In the original wording, the parenthesized sentence was, I think, an attempt to clarify the first sentence of the `@return` clause, since its use of "previous" is indeed confusing. Since we're rewording the main part of the clause to cover both the absent and was-mapped-to-null case, I don't think we need the parenthesized statement at all. How about:

> @return {@code null} if the specified key was absent or was associated with {@code null}, otherwise the value currently associated with the key

This largely mirrors the initial sentence of the method specification, but that's no bad thing; indeed, it's preferable to apparently contradicting it.

The "associated with null" wording is rather clumsy compared with "mapped to null" but most of the rest of the text here uses some form of "association" so I stuck with that.

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

PR Comment: https://git.openjdk.org/jdk/pull/17438#issuecomment-1944451781