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

[John Lin]

On Wed, 25 Nov 2020 20:22:21 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> @pavelrappo 
>> 
>>> What is the required level of fidelity particular (pseudo-) code has to have?
>> 
>> It's potentially a large discussion, one that could be had in the context of my JEP draft http://openjdk.java.net/jeps/8068562 . However, speaking practically, it's possible to focus the discussion fairly concisely: the main responsibility of the `@implSpec` ("Implementation Requirements") section is to give implementors of subclasses enough information to decide whether to inherit the implementation or to override it, and if they override it, what behavior they can expect if they were to call `super.compute`.
>> 
>> In this case, a null-value-tolerating Map implementation needs to know that the default implementation calls `remove` in the particular case that you mentioned. A concurrent Map implementation will also need to know that the default implementation calls `get(key)` and `containsKey(key)` at different times, potentially leading to a race condition. Both of these inform the override vs. inherit decision.
>
> @stuart-marks 
> 
>> Both of these inform the override vs. inherit decision.
> 
> So in this case - fixing the specification to match the default implementation seems to be the right call - as existing implementations that do not override are more probably depending on the current default behavior.

Thank you all for giving me great advice. Sounds like the conclusion is to update the documentation to match the default implementation. I'll update this PR and propose a new CSR accordingly.

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

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