Summary

The specification for the return value of Map::putIfAbsent is confusing.

Problem

The specification of the return value of Map::putIfAbsent mentions returning the previous value. However, as the call does nothing when there is a non-null current value, mentioning a previous value doesn't make sense.

Solution

Simplify and clarify the text of the @return tag as shown below.

Specification

--- a/src/java.base/share/classes/java/util/Map.java
+++ b/src/java.base/share/classes/java/util/Map.java
@@ -817,11 +817,8 @@ default void replaceAll(BiFunction<? super K, ? super V, ? extends V> function)
      *
      * @param key key with which the specified value is to be associated
      * @param value value to be associated with the specified key
-     * @return the previous value associated with the specified key, or
-     *         {@code null} if there was no mapping for the key.
-     *         (A {@code null} return can also indicate that the map
-     *         previously associated {@code null} with the key,
-     *         if the implementation supports null values.)
+     * @return {@code null} if the specified key was absent or was associated with
+     *         {@code null}, otherwise the value currently associated with the key
      * @throws UnsupportedOperationException if the {@code putIfAbsent} operation
      *         is not supported by this map
      *         ({@linkplain Collection##optional-restrictions optional})