From 61bce518aa79afc043d2460b25d4ebd548111558 Mon Sep 17 00:00:00 2001
From: Tagir Valeev <tagir.valeev@jetbrains.com>
Date: Wed, 2 Oct 2024 13:47:42 +0200
Subject: [PATCH] NotNullByDefault: refine the behavior for type parameters

---
 .../jetbrains/annotations/NotNullByDefault.java | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/src/jvmMain/java/org/jetbrains/annotations/NotNullByDefault.java b/src/jvmMain/java/org/jetbrains/annotations/NotNullByDefault.java
index 0caaaf6..833a9c7 100644
--- a/src/jvmMain/java/org/jetbrains/annotations/NotNullByDefault.java
+++ b/src/jvmMain/java/org/jetbrains/annotations/NotNullByDefault.java
@@ -21,8 +21,21 @@
  * The tools may issue a warning if the nullability for a subclass method contradicts from the specified nullability
  * of a superclass method.
  * <p>
- * The annotation has no effect on newly declared type parameters and their bounds. Only instantiations of
- * type parameters are constrained.
+ * For newly declared type parameters, the annotation applies to its bounds, including implicit {@code Object}
+ * bound if no explicit bound is declared. For example, {@code <T>} declared under {@code @NotNullByDefault} scope
+ * means the same as {@code <T extends @NotNull Object>}. To reset to default behavior in this case, one should use
+ * {@code <T extends @UnknownNullability Object>}.
+ * <p>
+ * The type parameter references are not affected by {@code @NotNullByDefault}. For example:
+ * <pre>{@code
+ * @NotNullByDefault
+ * interface Pair<K extends @Nullable Object, V> {
+ *   // Not assumed to be @NotNull; may return null depending on the T instantiation
+ *   K getKey();
+ *   // Returns @NotNull, as implicit upper bound of V is @NotNull Object,
+ *   // so it cannot be instantiated with a nullable type
+ *   V getValue();
+ * }}</pre>
  * <p>
  * The annotation has no effect on local variables.
  *