From f1dcbe7c9817099666b9307a7da0f0ad76c97f4a Mon Sep 17 00:00:00 2001 From: cpovirk Date: Wed, 10 Aug 2022 13:53:00 -0700 Subject: [PATCH] Attempt to improve documentation of `@ParametricNullness`. Fixes https://github.com/google/guava/issues/6126 ...at least the documentation part (hopefully), which is the best we can do for the moment. For progress on nullness annotations in general, watch for news in our release notes and eventually on https://github.com/google/guava/issues/2960 RELNOTES=n/a PiperOrigin-RevId: 466777864 --- .../common/base/ParametricNullness.java | 43 ++++++++++++++++--- .../common/cache/ParametricNullness.java | 43 ++++++++++++++++--- .../common/collect/ParametricNullness.java | 43 ++++++++++++++++--- .../common/escape/ParametricNullness.java | 43 ++++++++++++++++--- .../common/eventbus/ParametricNullness.java | 43 ++++++++++++++++--- .../common/graph/ParametricNullness.java | 43 ++++++++++++++++--- .../common/hash/ParametricNullness.java | 43 ++++++++++++++++--- .../common/html/ParametricNullness.java | 43 ++++++++++++++++--- .../google/common/io/ParametricNullness.java | 43 ++++++++++++++++--- .../common/math/ParametricNullness.java | 43 ++++++++++++++++--- .../google/common/net/ParametricNullness.java | 43 ++++++++++++++++--- .../common/primitives/ParametricNullness.java | 43 ++++++++++++++++--- .../common/reflect/ParametricNullness.java | 43 ++++++++++++++++--- .../util/concurrent/ParametricNullness.java | 43 ++++++++++++++++--- .../google/common/xml/ParametricNullness.java | 43 ++++++++++++++++--- .../common/base/ParametricNullness.java | 43 ++++++++++++++++--- .../common/cache/ParametricNullness.java | 43 ++++++++++++++++--- .../common/collect/ParametricNullness.java | 43 ++++++++++++++++--- .../common/escape/ParametricNullness.java | 43 ++++++++++++++++--- .../common/eventbus/ParametricNullness.java | 43 ++++++++++++++++--- .../common/graph/ParametricNullness.java | 43 ++++++++++++++++--- .../common/hash/ParametricNullness.java | 43 ++++++++++++++++--- .../common/html/ParametricNullness.java | 43 ++++++++++++++++--- .../google/common/io/ParametricNullness.java | 43 ++++++++++++++++--- .../common/math/ParametricNullness.java | 43 ++++++++++++++++--- .../google/common/net/ParametricNullness.java | 43 ++++++++++++++++--- .../common/primitives/ParametricNullness.java | 43 ++++++++++++++++--- .../common/reflect/ParametricNullness.java | 43 ++++++++++++++++--- .../util/concurrent/ParametricNullness.java | 43 ++++++++++++++++--- .../google/common/xml/ParametricNullness.java | 43 ++++++++++++++++--- 30 files changed, 1140 insertions(+), 150 deletions(-) diff --git a/android/guava/src/com/google/common/base/ParametricNullness.java b/android/guava/src/com/google/common/base/ParametricNullness.java index 5b595adb3ffb..0bcc65dc2eb5 100644 --- a/android/guava/src/com/google/common/base/ParametricNullness.java +++ b/android/guava/src/com/google/common/base/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + * + * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/cache/ParametricNullness.java b/android/guava/src/com/google/common/cache/ParametricNullness.java index 64682de55333..eaf194d4ab1c 100644 --- a/android/guava/src/com/google/common/cache/ParametricNullness.java +++ b/android/guava/src/com/google/common/cache/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/collect/ParametricNullness.java b/android/guava/src/com/google/common/collect/ParametricNullness.java index 94b1bcd3aaa2..207c05262e41 100644 --- a/android/guava/src/com/google/common/collect/ParametricNullness.java +++ b/android/guava/src/com/google/common/collect/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/escape/ParametricNullness.java b/android/guava/src/com/google/common/escape/ParametricNullness.java index d9412065ffd9..f964ca4a4f61 100644 --- a/android/guava/src/com/google/common/escape/ParametricNullness.java +++ b/android/guava/src/com/google/common/escape/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/eventbus/ParametricNullness.java b/android/guava/src/com/google/common/eventbus/ParametricNullness.java index ac91392f75eb..47c7d8d4d063 100644 --- a/android/guava/src/com/google/common/eventbus/ParametricNullness.java +++ b/android/guava/src/com/google/common/eventbus/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/graph/ParametricNullness.java b/android/guava/src/com/google/common/graph/ParametricNullness.java index 87ff930a4aac..32fd5ee7ecaa 100644 --- a/android/guava/src/com/google/common/graph/ParametricNullness.java +++ b/android/guava/src/com/google/common/graph/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/hash/ParametricNullness.java b/android/guava/src/com/google/common/hash/ParametricNullness.java index 460106c092ea..4ebc40bb741e 100644 --- a/android/guava/src/com/google/common/hash/ParametricNullness.java +++ b/android/guava/src/com/google/common/hash/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/html/ParametricNullness.java b/android/guava/src/com/google/common/html/ParametricNullness.java index 61b44616462b..50a64c781c90 100644 --- a/android/guava/src/com/google/common/html/ParametricNullness.java +++ b/android/guava/src/com/google/common/html/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/io/ParametricNullness.java b/android/guava/src/com/google/common/io/ParametricNullness.java index 98da765852b6..881c07d49804 100644 --- a/android/guava/src/com/google/common/io/ParametricNullness.java +++ b/android/guava/src/com/google/common/io/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/math/ParametricNullness.java b/android/guava/src/com/google/common/math/ParametricNullness.java index 8e57826e4335..612fa934a6d5 100644 --- a/android/guava/src/com/google/common/math/ParametricNullness.java +++ b/android/guava/src/com/google/common/math/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/net/ParametricNullness.java b/android/guava/src/com/google/common/net/ParametricNullness.java index 1ad2e27c0f4f..83b9eb6fa6a3 100644 --- a/android/guava/src/com/google/common/net/ParametricNullness.java +++ b/android/guava/src/com/google/common/net/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/primitives/ParametricNullness.java b/android/guava/src/com/google/common/primitives/ParametricNullness.java index 4289b9b164f1..c40ea499d4ce 100644 --- a/android/guava/src/com/google/common/primitives/ParametricNullness.java +++ b/android/guava/src/com/google/common/primitives/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/reflect/ParametricNullness.java b/android/guava/src/com/google/common/reflect/ParametricNullness.java index b6331ac26b0b..372a53bb616f 100644 --- a/android/guava/src/com/google/common/reflect/ParametricNullness.java +++ b/android/guava/src/com/google/common/reflect/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/util/concurrent/ParametricNullness.java b/android/guava/src/com/google/common/util/concurrent/ParametricNullness.java index a745bf7bb4b8..e8fcce6ee681 100644 --- a/android/guava/src/com/google/common/util/concurrent/ParametricNullness.java +++ b/android/guava/src/com/google/common/util/concurrent/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/android/guava/src/com/google/common/xml/ParametricNullness.java b/android/guava/src/com/google/common/xml/ParametricNullness.java index e4e5d12f0e3b..439707a2edb1 100644 --- a/android/guava/src/com/google/common/xml/ParametricNullness.java +++ b/android/guava/src/com/google/common/xml/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/base/ParametricNullness.java b/guava/src/com/google/common/base/ParametricNullness.java index 5b595adb3ffb..0bcc65dc2eb5 100644 --- a/guava/src/com/google/common/base/ParametricNullness.java +++ b/guava/src/com/google/common/base/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/cache/ParametricNullness.java b/guava/src/com/google/common/cache/ParametricNullness.java index 64682de55333..eaf194d4ab1c 100644 --- a/guava/src/com/google/common/cache/ParametricNullness.java +++ b/guava/src/com/google/common/cache/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/collect/ParametricNullness.java b/guava/src/com/google/common/collect/ParametricNullness.java index 94b1bcd3aaa2..207c05262e41 100644 --- a/guava/src/com/google/common/collect/ParametricNullness.java +++ b/guava/src/com/google/common/collect/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/escape/ParametricNullness.java b/guava/src/com/google/common/escape/ParametricNullness.java index d9412065ffd9..f964ca4a4f61 100644 --- a/guava/src/com/google/common/escape/ParametricNullness.java +++ b/guava/src/com/google/common/escape/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/eventbus/ParametricNullness.java b/guava/src/com/google/common/eventbus/ParametricNullness.java index ac91392f75eb..47c7d8d4d063 100644 --- a/guava/src/com/google/common/eventbus/ParametricNullness.java +++ b/guava/src/com/google/common/eventbus/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/graph/ParametricNullness.java b/guava/src/com/google/common/graph/ParametricNullness.java index 87ff930a4aac..32fd5ee7ecaa 100644 --- a/guava/src/com/google/common/graph/ParametricNullness.java +++ b/guava/src/com/google/common/graph/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/hash/ParametricNullness.java b/guava/src/com/google/common/hash/ParametricNullness.java index 460106c092ea..4ebc40bb741e 100644 --- a/guava/src/com/google/common/hash/ParametricNullness.java +++ b/guava/src/com/google/common/hash/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/html/ParametricNullness.java b/guava/src/com/google/common/html/ParametricNullness.java index 61b44616462b..50a64c781c90 100644 --- a/guava/src/com/google/common/html/ParametricNullness.java +++ b/guava/src/com/google/common/html/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/io/ParametricNullness.java b/guava/src/com/google/common/io/ParametricNullness.java index 98da765852b6..881c07d49804 100644 --- a/guava/src/com/google/common/io/ParametricNullness.java +++ b/guava/src/com/google/common/io/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/math/ParametricNullness.java b/guava/src/com/google/common/math/ParametricNullness.java index 8e57826e4335..612fa934a6d5 100644 --- a/guava/src/com/google/common/math/ParametricNullness.java +++ b/guava/src/com/google/common/math/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/net/ParametricNullness.java b/guava/src/com/google/common/net/ParametricNullness.java index 1ad2e27c0f4f..83b9eb6fa6a3 100644 --- a/guava/src/com/google/common/net/ParametricNullness.java +++ b/guava/src/com/google/common/net/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/primitives/ParametricNullness.java b/guava/src/com/google/common/primitives/ParametricNullness.java index 4289b9b164f1..c40ea499d4ce 100644 --- a/guava/src/com/google/common/primitives/ParametricNullness.java +++ b/guava/src/com/google/common/primitives/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/reflect/ParametricNullness.java b/guava/src/com/google/common/reflect/ParametricNullness.java index b6331ac26b0b..372a53bb616f 100644 --- a/guava/src/com/google/common/reflect/ParametricNullness.java +++ b/guava/src/com/google/common/reflect/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/util/concurrent/ParametricNullness.java b/guava/src/com/google/common/util/concurrent/ParametricNullness.java index a745bf7bb4b8..e8fcce6ee681 100644 --- a/guava/src/com/google/common/util/concurrent/ParametricNullness.java +++ b/guava/src/com/google/common/util/concurrent/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME) diff --git a/guava/src/com/google/common/xml/ParametricNullness.java b/guava/src/com/google/common/xml/ParametricNullness.java index e4e5d12f0e3b..439707a2edb1 100644 --- a/guava/src/com/google/common/xml/ParametricNullness.java +++ b/guava/src/com/google/common/xml/ParametricNullness.java @@ -26,23 +26,56 @@ import java.lang.annotation.Target; /** - * Marks a "top-level" type-variable usage as the closest we can get to "non-nullable when - * non-nullable; nullable when nullable" (like the Android {@code - * NullFromTypeParam}). + * Annotates a "top-level" type-variable usage that takes its nullness from the type argument + * supplied by the user of the class. For example, {@code Multiset.Entry.getElement()} returns + * {@code @ParametricNullness E}, which means: + * + *

+ * + * This is the same behavior as type-variable usages have to Kotlin and to the Checker Framework. + * Contrast the method above to: + * + * * *

Consumers of this annotation include: * *

* + *

This annotation is a temporary hack. We will remove it after we're able to adopt the JSpecify nullness annotations and tools no longer need + * it. */ @GwtCompatible @Retention(RUNTIME)