Turn @ParametricNullness into a no-op for Kotlin and IntelliJ, and …

…reduce its retention to `CLASS`. We'll continue annotating our APIs with it for now, since it can be helpful for NullAway and perhaps other tools. (But please [let us know](https://github.com/google/guava/issues/new?template=Blank+issue) if you are depending on it from a tool other than NullAway.) This is the next step toward [using JSpecify in Guava](jspecify/jspecify#239 (comment)). Also, I've updated the Javadoc to belatedly note that `ParametricNulless` isn't used by `NullPointerTester` anymore (as of cl/530341970). RELNOTES=Changed `@ParametricNullness` into a no-op for Kotlin and IntelliJ. Before now, it was forcing many usages of type variables to have [platform types](https://kotlinlang.org/docs/java-interop.html#null-safety-and-platform-types), which meant that Kotlin couldn't check those usages for nullness errors. With this change, Kotlin can detect more errors. PiperOrigin-RevId: 708610470
google · Dec 21, 2024 · ae36f57 · ae36f57
1 parent 17634b5
commit ae36f57
Show file tree

Hide file tree

Showing 30 changed files with 270 additions and 660 deletions.
diff --git a/android/guava/src/com/google/common/base/ParametricNullness.java b/android/guava/src/com/google/common/base/ParametricNullness.java
@@ -19,7 +19,7 @@
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.PARAMETER;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import static java.lang.annotation.RetentionPolicy.CLASS;
 
 import com.google.common.annotations.GwtCompatible;
 import java.lang.annotation.Retention;
@@ -54,32 +54,19 @@
  * <p>Consumers of this annotation include:
  *
  * <ul>
- *   <li>Kotlin, for which it makes the type-variable usage (a) a Kotlin platform type when the type
- *       argument is non-nullable and (b) nullable when the type argument is nullable. We use this
- *       to reduce the immediate effects of {@code NullMarked} as we transition to JSpecify
- *       annotations.
- *   <li>NullAway, which will <a
- *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treat it
- *       identically to {@code Nullable} as of version 0.9.9</a>. To treat it that way before then,
- *       you can set {@code
- *       -XepOpt:NullAway:CustomNullableAnnotations=com.google.common.base.ParametricNullness,...,com.google.common.util.concurrent.ParametricNullness},
- *       where the {@code ...} contains the names of all the other {@code ParametricNullness}
- *       annotations in Guava. Or you might prefer to omit Guava from your {@code AnnotatedPackages}
- *       list.
- *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>
- *   <li>{@code NullPointerTester}, at least in the Android backport (where the type-use annotations
- *       {@code NullPointerTester} would need are not available) and in case of <a
- *       href="https://bugs.openjdk.java.net/browse/JDK-8202469">JDK-8202469</a>
+ *   <li>NullAway, which <a
+ *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treats it
+ *       identically to {@code Nullable}</a> as of version 0.9.9.
+ *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>, maybe: It might no longer be
+ *       necessary there, since we have stopped using the {@code @ParametersAreNonnullByDefault}
+ *       annotations that {@code ParametricNullness} was counteracting.
  * </ul>
  *
- * <p>This annotation is a temporary hack. We will remove it after we're able to adopt the <a
- * href="https://jspecify.dev/">JSpecify</a> nullness annotations and <a
+ * <p>This annotation is a temporary hack. We will remove it after <a
  * href="https://github.com/google/guava/issues/6126#issuecomment-1203145963">tools no longer need
  * it</a>.
  */
 @GwtCompatible
-@Retention(RUNTIME)
+@Retention(CLASS)
 @Target({FIELD, METHOD, PARAMETER})
-@javax.annotation.meta.TypeQualifierNickname
-@javax.annotation.Nonnull(when = javax.annotation.meta.When.UNKNOWN)
 @interface ParametricNullness {}
diff --git a/android/guava/src/com/google/common/cache/ParametricNullness.java b/android/guava/src/com/google/common/cache/ParametricNullness.java
@@ -19,7 +19,7 @@
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.PARAMETER;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import static java.lang.annotation.RetentionPolicy.CLASS;
 
 import com.google.common.annotations.GwtCompatible;
 import java.lang.annotation.Retention;
@@ -54,32 +54,19 @@
  * <p>Consumers of this annotation include:
  *
  * <ul>
- *   <li>Kotlin, for which it makes the type-variable usage (a) a Kotlin platform type when the type
- *       argument is non-nullable and (b) nullable when the type argument is nullable. We use this
- *       to reduce the immediate effects of {@code NullMarked} as we transition to JSpecify
- *       annotations.
- *   <li>NullAway, which will <a
- *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treat it
- *       identically to {@code Nullable} as of version 0.9.9</a>. To treat it that way before then,
- *       you can set {@code
- *       -XepOpt:NullAway:CustomNullableAnnotations=com.google.common.base.ParametricNullness,...,com.google.common.util.concurrent.ParametricNullness},
- *       where the {@code ...} contains the names of all the other {@code ParametricNullness}
- *       annotations in Guava. Or you might prefer to omit Guava from your {@code AnnotatedPackages}
- *       list.
- *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>
- *   <li>{@code NullPointerTester}, at least in the Android backport (where the type-use annotations
- *       {@code NullPointerTester} would need are not available) and in case of <a
- *       href="https://bugs.openjdk.java.net/browse/JDK-8202469">JDK-8202469</a>
+ *   <li>NullAway, which <a
+ *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treats it
+ *       identically to {@code Nullable}</a> as of version 0.9.9.
+ *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>, maybe: It might no longer be
+ *       necessary there, since we have stopped using the {@code @ParametersAreNonnullByDefault}
+ *       annotations that {@code ParametricNullness} was counteracting.
  * </ul>
  *
- * <p>This annotation is a temporary hack. We will remove it after we're able to adopt the <a
- * href="https://jspecify.dev/">JSpecify</a> nullness annotations and <a
+ * <p>This annotation is a temporary hack. We will remove it after <a
  * href="https://github.com/google/guava/issues/6126#issuecomment-1203145963">tools no longer need
  * it</a>.
  */
 @GwtCompatible
-@Retention(RUNTIME)
+@Retention(CLASS)
 @Target({FIELD, METHOD, PARAMETER})
-@javax.annotation.meta.TypeQualifierNickname
-@javax.annotation.Nonnull(when = javax.annotation.meta.When.UNKNOWN)
 @interface ParametricNullness {}
diff --git a/android/guava/src/com/google/common/collect/ParametricNullness.java b/android/guava/src/com/google/common/collect/ParametricNullness.java
@@ -19,7 +19,7 @@
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.PARAMETER;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import static java.lang.annotation.RetentionPolicy.CLASS;
 
 import com.google.common.annotations.GwtCompatible;
 import java.lang.annotation.Retention;
@@ -54,32 +54,19 @@
  * <p>Consumers of this annotation include:
  *
  * <ul>
- *   <li>Kotlin, for which it makes the type-variable usage (a) a Kotlin platform type when the type
- *       argument is non-nullable and (b) nullable when the type argument is nullable. We use this
- *       to reduce the immediate effects of {@code NullMarked} as we transition to JSpecify
- *       annotations.
- *   <li>NullAway, which will <a
- *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treat it
- *       identically to {@code Nullable} as of version 0.9.9</a>. To treat it that way before then,
- *       you can set {@code
- *       -XepOpt:NullAway:CustomNullableAnnotations=com.google.common.base.ParametricNullness,...,com.google.common.util.concurrent.ParametricNullness},
- *       where the {@code ...} contains the names of all the other {@code ParametricNullness}
- *       annotations in Guava. Or you might prefer to omit Guava from your {@code AnnotatedPackages}
- *       list.
- *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>
- *   <li>{@code NullPointerTester}, at least in the Android backport (where the type-use annotations
- *       {@code NullPointerTester} would need are not available) and in case of <a
- *       href="https://bugs.openjdk.java.net/browse/JDK-8202469">JDK-8202469</a>
+ *   <li>NullAway, which <a
+ *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treats it
+ *       identically to {@code Nullable}</a> as of version 0.9.9.
+ *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>, maybe: It might no longer be
+ *       necessary there, since we have stopped using the {@code @ParametersAreNonnullByDefault}
+ *       annotations that {@code ParametricNullness} was counteracting.
  * </ul>
  *
- * <p>This annotation is a temporary hack. We will remove it after we're able to adopt the <a
- * href="https://jspecify.dev/">JSpecify</a> nullness annotations and <a
+ * <p>This annotation is a temporary hack. We will remove it after <a
  * href="https://github.com/google/guava/issues/6126#issuecomment-1203145963">tools no longer need
  * it</a>.
  */
 @GwtCompatible
-@Retention(RUNTIME)
+@Retention(CLASS)
 @Target({FIELD, METHOD, PARAMETER})
-@javax.annotation.meta.TypeQualifierNickname
-@javax.annotation.Nonnull(when = javax.annotation.meta.When.UNKNOWN)
 @interface ParametricNullness {}
diff --git a/android/guava/src/com/google/common/escape/ParametricNullness.java b/android/guava/src/com/google/common/escape/ParametricNullness.java
@@ -19,7 +19,7 @@
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.PARAMETER;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import static java.lang.annotation.RetentionPolicy.CLASS;
 
 import com.google.common.annotations.GwtCompatible;
 import java.lang.annotation.Retention;
@@ -54,32 +54,19 @@
  * <p>Consumers of this annotation include:
  *
  * <ul>
- *   <li>Kotlin, for which it makes the type-variable usage (a) a Kotlin platform type when the type
- *       argument is non-nullable and (b) nullable when the type argument is nullable. We use this
- *       to reduce the immediate effects of {@code NullMarked} as we transition to JSpecify
- *       annotations.
- *   <li>NullAway, which will <a
- *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treat it
- *       identically to {@code Nullable} as of version 0.9.9</a>. To treat it that way before then,
- *       you can set {@code
- *       -XepOpt:NullAway:CustomNullableAnnotations=com.google.common.base.ParametricNullness,...,com.google.common.util.concurrent.ParametricNullness},
- *       where the {@code ...} contains the names of all the other {@code ParametricNullness}
- *       annotations in Guava. Or you might prefer to omit Guava from your {@code AnnotatedPackages}
- *       list.
- *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>
- *   <li>{@code NullPointerTester}, at least in the Android backport (where the type-use annotations
- *       {@code NullPointerTester} would need are not available) and in case of <a
- *       href="https://bugs.openjdk.java.net/browse/JDK-8202469">JDK-8202469</a>
+ *   <li>NullAway, which <a
+ *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treats it
+ *       identically to {@code Nullable}</a> as of version 0.9.9.
+ *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>, maybe: It might no longer be
+ *       necessary there, since we have stopped using the {@code @ParametersAreNonnullByDefault}
+ *       annotations that {@code ParametricNullness} was counteracting.
  * </ul>
  *
- * <p>This annotation is a temporary hack. We will remove it after we're able to adopt the <a
- * href="https://jspecify.dev/">JSpecify</a> nullness annotations and <a
+ * <p>This annotation is a temporary hack. We will remove it after <a
  * href="https://github.com/google/guava/issues/6126#issuecomment-1203145963">tools no longer need
  * it</a>.
  */
 @GwtCompatible
-@Retention(RUNTIME)
+@Retention(CLASS)
 @Target({FIELD, METHOD, PARAMETER})
-@javax.annotation.meta.TypeQualifierNickname
-@javax.annotation.Nonnull(when = javax.annotation.meta.When.UNKNOWN)
 @interface ParametricNullness {}
diff --git a/android/guava/src/com/google/common/eventbus/ParametricNullness.java b/android/guava/src/com/google/common/eventbus/ParametricNullness.java
@@ -19,7 +19,7 @@
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.PARAMETER;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import static java.lang.annotation.RetentionPolicy.CLASS;
 
 import com.google.common.annotations.GwtCompatible;
 import java.lang.annotation.Retention;
@@ -54,32 +54,19 @@
  * <p>Consumers of this annotation include:
  *
  * <ul>
- *   <li>Kotlin, for which it makes the type-variable usage (a) a Kotlin platform type when the type
- *       argument is non-nullable and (b) nullable when the type argument is nullable. We use this
- *       to reduce the immediate effects of {@code NullMarked} as we transition to JSpecify
- *       annotations.
- *   <li>NullAway, which will <a
- *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treat it
- *       identically to {@code Nullable} as of version 0.9.9</a>. To treat it that way before then,
- *       you can set {@code
- *       -XepOpt:NullAway:CustomNullableAnnotations=com.google.common.base.ParametricNullness,...,com.google.common.util.concurrent.ParametricNullness},
- *       where the {@code ...} contains the names of all the other {@code ParametricNullness}
- *       annotations in Guava. Or you might prefer to omit Guava from your {@code AnnotatedPackages}
- *       list.
- *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>
- *   <li>{@code NullPointerTester}, at least in the Android backport (where the type-use annotations
- *       {@code NullPointerTester} would need are not available) and in case of <a
- *       href="https://bugs.openjdk.java.net/browse/JDK-8202469">JDK-8202469</a>
+ *   <li>NullAway, which <a
+ *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treats it
+ *       identically to {@code Nullable}</a> as of version 0.9.9.
+ *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>, maybe: It might no longer be
+ *       necessary there, since we have stopped using the {@code @ParametersAreNonnullByDefault}
+ *       annotations that {@code ParametricNullness} was counteracting.
  * </ul>
  *
- * <p>This annotation is a temporary hack. We will remove it after we're able to adopt the <a
- * href="https://jspecify.dev/">JSpecify</a> nullness annotations and <a
+ * <p>This annotation is a temporary hack. We will remove it after <a
  * href="https://github.com/google/guava/issues/6126#issuecomment-1203145963">tools no longer need
  * it</a>.
  */
 @GwtCompatible
-@Retention(RUNTIME)
+@Retention(CLASS)
 @Target({FIELD, METHOD, PARAMETER})
-@javax.annotation.meta.TypeQualifierNickname
-@javax.annotation.Nonnull(when = javax.annotation.meta.When.UNKNOWN)
 @interface ParametricNullness {}
diff --git a/android/guava/src/com/google/common/graph/ParametricNullness.java b/android/guava/src/com/google/common/graph/ParametricNullness.java
@@ -19,7 +19,7 @@
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.PARAMETER;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import static java.lang.annotation.RetentionPolicy.CLASS;
 
 import com.google.common.annotations.GwtCompatible;
 import java.lang.annotation.Retention;
@@ -54,32 +54,19 @@
  * <p>Consumers of this annotation include:
  *
  * <ul>
- *   <li>Kotlin, for which it makes the type-variable usage (a) a Kotlin platform type when the type
- *       argument is non-nullable and (b) nullable when the type argument is nullable. We use this
- *       to reduce the immediate effects of {@code NullMarked} as we transition to JSpecify
- *       annotations.
- *   <li>NullAway, which will <a
- *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treat it
- *       identically to {@code Nullable} as of version 0.9.9</a>. To treat it that way before then,
- *       you can set {@code
- *       -XepOpt:NullAway:CustomNullableAnnotations=com.google.common.base.ParametricNullness,...,com.google.common.util.concurrent.ParametricNullness},
- *       where the {@code ...} contains the names of all the other {@code ParametricNullness}
- *       annotations in Guava. Or you might prefer to omit Guava from your {@code AnnotatedPackages}
- *       list.
- *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>
- *   <li>{@code NullPointerTester}, at least in the Android backport (where the type-use annotations
- *       {@code NullPointerTester} would need are not available) and in case of <a
- *       href="https://bugs.openjdk.java.net/browse/JDK-8202469">JDK-8202469</a>
+ *   <li>NullAway, which <a
+ *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treats it
+ *       identically to {@code Nullable}</a> as of version 0.9.9.
+ *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>, maybe: It might no longer be
+ *       necessary there, since we have stopped using the {@code @ParametersAreNonnullByDefault}
+ *       annotations that {@code ParametricNullness} was counteracting.
  * </ul>
  *
- * <p>This annotation is a temporary hack. We will remove it after we're able to adopt the <a
- * href="https://jspecify.dev/">JSpecify</a> nullness annotations and <a
+ * <p>This annotation is a temporary hack. We will remove it after <a
  * href="https://github.com/google/guava/issues/6126#issuecomment-1203145963">tools no longer need
  * it</a>.
  */
 @GwtCompatible
-@Retention(RUNTIME)
+@Retention(CLASS)
 @Target({FIELD, METHOD, PARAMETER})
-@javax.annotation.meta.TypeQualifierNickname
-@javax.annotation.Nonnull(when = javax.annotation.meta.When.UNKNOWN)
 @interface ParametricNullness {}
diff --git a/android/guava/src/com/google/common/hash/ParametricNullness.java b/android/guava/src/com/google/common/hash/ParametricNullness.java
@@ -19,7 +19,7 @@
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.PARAMETER;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import static java.lang.annotation.RetentionPolicy.CLASS;
 
 import com.google.common.annotations.GwtCompatible;
 import java.lang.annotation.Retention;
@@ -54,32 +54,19 @@
  * <p>Consumers of this annotation include:
  *
  * <ul>
- *   <li>Kotlin, for which it makes the type-variable usage (a) a Kotlin platform type when the type
- *       argument is non-nullable and (b) nullable when the type argument is nullable. We use this
- *       to reduce the immediate effects of {@code NullMarked} as we transition to JSpecify
- *       annotations.
- *   <li>NullAway, which will <a
- *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treat it
- *       identically to {@code Nullable} as of version 0.9.9</a>. To treat it that way before then,
- *       you can set {@code
- *       -XepOpt:NullAway:CustomNullableAnnotations=com.google.common.base.ParametricNullness,...,com.google.common.util.concurrent.ParametricNullness},
- *       where the {@code ...} contains the names of all the other {@code ParametricNullness}
- *       annotations in Guava. Or you might prefer to omit Guava from your {@code AnnotatedPackages}
- *       list.
- *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>
- *   <li>{@code NullPointerTester}, at least in the Android backport (where the type-use annotations
- *       {@code NullPointerTester} would need are not available) and in case of <a
- *       href="https://bugs.openjdk.java.net/browse/JDK-8202469">JDK-8202469</a>
+ *   <li>NullAway, which <a
+ *       href="https://github.com/google/guava/issues/6126#issuecomment-1204399671">treats it
+ *       identically to {@code Nullable}</a> as of version 0.9.9.
+ *   <li><a href="https://developers.google.com/j2objc">J2ObjC</a>, maybe: It might no longer be
+ *       necessary there, since we have stopped using the {@code @ParametersAreNonnullByDefault}
+ *       annotations that {@code ParametricNullness} was counteracting.
  * </ul>
  *
- * <p>This annotation is a temporary hack. We will remove it after we're able to adopt the <a
- * href="https://jspecify.dev/">JSpecify</a> nullness annotations and <a
+ * <p>This annotation is a temporary hack. We will remove it after <a
  * href="https://github.com/google/guava/issues/6126#issuecomment-1203145963">tools no longer need
  * it</a>.
  */
 @GwtCompatible
-@Retention(RUNTIME)
+@Retention(CLASS)
 @Target({FIELD, METHOD, PARAMETER})
-@javax.annotation.meta.TypeQualifierNickname
-@javax.annotation.Nonnull(when = javax.annotation.meta.When.UNKNOWN)
 @interface ParametricNullness {}