RFR: 8247402: Documentation for Map::compute contains confusing implementation requirements

[Pavel Rappo]

On Mon, 23 Nov 2020 14:35:37 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> The proposed CSR has a few problems that we need to resolve.
> 
> 1. The **Specification** pseudo-code behaves differently from both the old pseudo-code and the actual implementation when `newValue == null && oldValue == null` and `map.containsKey(key) == true`.
> 2. The content of the **Solution** section seems irrelevant: aside from a couple of missing `return` statements the current pseudo-code is fine. We are after something else, aren't we? The bottom line is we should state the solution more clearly.
> 3. The **Summary** section differs from that of the JDK-8247402.

I read my previous reply and realized that it is confusing and contains a factual error; so let me straighten it out in this new reply rather than edit that previous one.

1. The proposed pseudo-code behaves exactly the same way as the existing pseudo-code modulo the missing `return` statements. (For some reason, I previously wrote that the proposed pseudo-code behaves differently from the existing pseudo-code.)
2. Both the proposed pseudo-code and the existing pseudo-code deviate from the documented behaviour (written in prose) and the actual implementation. The deviation happens when `newValue == null && (oldValue = map.get(key)) == null` and `map.containsKey(key) == true`. (That part was correct.)

Now, here's what I should have said in my previous reply. If the CSR intends to solve (2) then both the proposed pseudo-code and the **Problem** section must be updated; otherwise the **Solution** section must be updated. Put differently, either fix the diff and add one more item to that problem list, or change the solution. Otherwise the solution does not match the problem leaving the CSR in a contradictory state.

I hope this all makes sense now.

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

PR: https://git.openjdk.java.net/jdk/pull/714