From 5a220a37d60876c20bed94a1bdde9b336d8187e7 Mon Sep 17 00:00:00 2001
From: Chris Povirk <cpovirk@google.com>
Date: Mon, 7 Oct 2024 11:30:51 -0400
Subject: [PATCH] Comment upon our choice for annotations for `forEach*`.

---
 .../classes/java/util/concurrent/ConcurrentHashMap.java   | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java b/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java
index 4315823ead1..809ae36f9b9 100644
--- a/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java
+++ b/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java
@@ -3742,6 +3742,11 @@ public void forEach(long parallelismThreshold,
      * @param <U> the return type of the transformer
      * @since 1.8
      */
+    // JSpecify: We could instead use `<U extends @Nullable Object>` along with `@NonNull U`.
+    // Advantages to our current approach include:
+    // - calls out the null support in an otherwise null-hostile class
+    // - is consistent with the declarations for `search` and `reduce`
+    // - saves the user from a decision: https://github.com/jspecify/jspecify/issues/525
     public <U> void forEach(long parallelismThreshold,
                             BiFunction<? super K, ? super V, ? extends @Nullable U> transformer,
                             Consumer<? super U> action) {
@@ -3909,6 +3914,7 @@ public void forEachKey(long parallelismThreshold,
      * @param <U> the return type of the transformer
      * @since 1.8
      */
+    // JSpecify: See discussion on `forEach` above.
     public <U> void forEachKey(long parallelismThreshold,
                                Function<? super K, ? extends @Nullable U> transformer,
                                Consumer<? super U> action) {
@@ -4096,6 +4102,7 @@ public void forEachValue(long parallelismThreshold,
      * @param <U> the return type of the transformer
      * @since 1.8
      */
+    // JSpecify: See discussion on `forEach` above.
     public <U> void forEachValue(long parallelismThreshold,
                                  Function<? super V, ? extends @Nullable U> transformer,
                                  Consumer<? super U> action) {
@@ -4280,6 +4287,7 @@ public void forEachEntry(long parallelismThreshold,
      * @param <U> the return type of the transformer
      * @since 1.8
      */
+    // JSpecify: See discussion on `forEach` above.
     public <U> void forEachEntry(long parallelismThreshold,
                                  Function<Map.Entry<K,V>, ? extends @Nullable U> transformer,
                                  Consumer<? super U> action) {