Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8257768

Documentation for Map::compute contains confusing implementation requirements

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 16
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      There are no implementation changes; this doc-comment change removes internal inconsistencies between the code snippet and its prose counterpart in the method specification.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      The implementation requirement of Map::compute does not match its default implementation. Besides, it has some other minor issues. We should fix it.

      Problem

      The documentation of the implementation requirements for Map::compute has the following problems:

      1. It doesn't match its default implementation.
      2. It lacks of the return statements for most of the if-else cases.
      3. The indents are 3 spaces, while the convention is 4 spaces.
      4. The if-else is overly complicated and can be simplified.
      5. The surrounding prose contains incorrect statements.

      Solution

      Rewrite the documentation of Map::compute to match its default implementation and solve the above mentioned problems.

      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..b30e3979259 100644
      --- a/src/java.base/share/classes/java/util/Map.java
      +++ b/src/java.base/share/classes/java/util/Map.java
      @@ -1107,23 +1107,17 @@ public interface Map<K, V> {
            *
            * @implSpec
            * The default implementation is equivalent to performing the following
      -     * steps for this {@code map}, then returning the current value or
      -     * {@code null} if absent:
      +     * steps for this {@code map}:
            *
            * <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.containsKey(key)) {
      +     *     map.remove(key);
            * }
      +     * return newValue;
            * }</pre>
            *
            * <p>The default implementation makes no guarantees about detecting if the

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              prappo Pavel Rappo
              Reporter:
              webbuggrp Webbug Group
              Reviewed By:
              Daniel Fuchs, Martin Buchholz, Stuart Marks
              Votes:
              0 Vote for this issue
              Watchers:
              6 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: