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

[John Lin]

On Wed, 18 Nov 2020 14:16:03 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> @dfuch May I ask how can I create a CSR? I checked https://wiki.openjdk.java.net/display/csr/CSR+FAQs and it says:
>> 
>>> Q: How do I create a CSR ?
>>> A: Do not directly create a CSR from the Create Menu. JIRA will let you do this right up until the moment you try to save it and find your typing was in vain.
>>> Instead you should go to the target bug, select "More", and from the drop down menu select "Create CSR". This is required to properly associate the CSR with the main bug, just as is done for backports.
>> 
>> However, I don't have an account at https://bugs.openjdk.java.net/ yet. Therefore, I don't see the "More" button on https://bugs.openjdk.java.net/browse/JDK-8247402. Could you please tell me how do I proceed? Thank you.
>
> @johnlinp, you cannot create a CSR by yourself at the moment. Someone else will have to do that for you. Might as well be me. So here's my proposal: come up with the meat, then I'll help you with the paperwork. 
> 
> For starters, have a look at existing CSRs (you don't need a JBS account for that). For example, https://bugs.openjdk.java.net/issues/?jql=issuetype%3DCSR%20and%20Subcomponent%3Djava.util%3Acollections%20
> 
> Fill in an informal CSR template inline in this thread, and we'll proceed from that point. Is that okay?

@pavelrappo Please see my proposed CSR below. Thank you.

# Map::compute should have a clearer implementation requirement.

## Summary

java.util.Map::compute should have a clearer implementation requirement in its documentation.

## Problem

The documentation of the implementation requirements for Map::compute has the following problems:
1. It lacks of return statements for most of the if-else cases.
1. The indents are 3 spaces, while the convention is 4 spaces.
1. The if-else is overly complicated and can be simplified.

## Solution

Rewrite the documentation of Map::compute to match its default implementation.

## Specification

diff --git a/src/java.base/share/classes/java/util/Map.java b/src/java.base/share/classes/java/util/Map.java
index b1de34b42a5..c3118a90581 100644
--- a/src/java.base/share/classes/java/util/Map.java
+++ b/src/java.base/share/classes/java/util/Map.java
@@ -1113,17 +1113,12 @@ public interface Map<K, V> {
      * <pre> {@code
      * V oldValue = map.get(key);
      * V newValue = remappingFunction.apply(key, oldValue);
-     * if (oldValue != null) {
-     *    if (newValue != null)
-     *       map.put(key, newValue);
-     *    else
-     *       map.remove(key);
-     * } else {
-     *    if (newValue != null)
-     *       map.put(key, newValue);
-     *    else
-     *       return null;
+     * if (newValue != null) {
+     *     map.put(key, newValue);
+     * } else if (oldValue != null) {
+     *     map.remove(key);
      * }
+     * return newValue;
      * }</pre>
      *
      * <p>The default implementation makes no guarantees about detecting if the

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

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