From 5fc14f73ed9a67deb759447424e9c993c98a9f97 Mon Sep 17 00:00:00 2001
From: Sarah Haggarty <sarahhaggarty@users.noreply.github.com>
Date: Thu, 3 Aug 2023 17:32:52 +0200
Subject: [PATCH] update: add definitely non-nullable types documentation

---
 docs/topics/generics.md                       | 35 +++++++++++++++++++
 .../jvm/java-to-kotlin-nullability-guide.md   | 30 ++++++++++++++++
 docs/topics/null-safety.md                    |  3 +-
 3 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/docs/topics/generics.md b/docs/topics/generics.md
index 70ec337e3ad..8a9c60ea22c 100644
--- a/docs/topics/generics.md
+++ b/docs/topics/generics.md
@@ -322,6 +322,41 @@ fun <T> copyWhenGreater(list: List<T>, threshold: T): List<String>
 The passed type must satisfy all conditions of the `where` clause simultaneously. In the above example, the `T` type
 must implement _both_ `CharSequence` and `Comparable`.
 
+## Definitely non-nullable types
+
+To make interoperability with generic Java classes and interfaces easier, Kotlin supports declaring a generic type parameter
+as **definitely non-nullable**. 
+
+To declare a generic type `T` as definitely non-nullable, declare the type with `& Any`. For example: `T & Any`.
+
+A definitely non-nullable type must have a nullable [upper bound](#upper-bounds).
+
+The most common use case for declaring definitely non-nullable types is when you want to override a Java method that 
+contains `@NotNull` as an argument. For example, consider the `load()` method:
+
+```java
+import org.jetbrains.annotations.*;
+
+public interface Game<T> {
+    public T save(T x) {}
+    @NotNull
+    public T load(@NotNull T x) {}
+}
+```
+
+To override the `load()` method in Kotlin successfully, you need `T1` to be declared as definitely non-nullable:
+
+```kotlin
+interface ArcadeGame<T1> : Game<T1> {
+    override fun save(x: T1): T1
+    // T1 is definitely non-nullable
+    override fun load(x: T1 & Any): T1 & Any
+}
+```
+
+When working only with Kotlin, it's unlikely that you will need to declare definitely non-nullable types explicitly because 
+Kotlin's type inference takes care of this for you.
+
 ## Type erasure
 
 The type safety checks that Kotlin performs for generic declaration usages are done at compile time.
diff --git a/docs/topics/jvm/java-to-kotlin-nullability-guide.md b/docs/topics/jvm/java-to-kotlin-nullability-guide.md
index 31bac535736..743e9dc9e9a 100644
--- a/docs/topics/jvm/java-to-kotlin-nullability-guide.md
+++ b/docs/topics/jvm/java-to-kotlin-nullability-guide.md
@@ -116,6 +116,36 @@ on a value of a non-nullable type.
 
 Learn more about [calling Java from Kotlin in regard to null-safety and platform types](java-interop.md#null-safety-and-platform-types).
 
+## Support for definitely non-nullable types
+
+In Kotlin, if you want to override a Java method that contains `@NotNull` as an argument, you need Kotlin's definitely
+non-nullable types.
+
+For example, consider this `load()` method in Java:
+
+```java
+import org.jetbrains.annotations.*;
+
+public interface Game<T> {
+  public T save(T x) {}
+  @NotNull
+  public T load(@NotNull T x) {}
+}
+```
+
+To override the `load()` method in Kotlin successfully, you need `T1` to be declared as definitely
+non-nullable (`T1 & Any`):
+
+```kotlin
+interface ArcadeGame<T1> : Game<T1> {
+  override fun save(x: T1): T1
+  // T1 is definitely non-nullable
+  override fun load(x: T1 & Any): T1 & Any
+}
+```
+
+Learn more about generic types that are [definitely non-nullable](generics.md#definitely-non-nullable-types).
+
 ## Checking the result of a function call
 
 One of the most common situations where you need to check for `null` is when you obtain a result from a function call.
diff --git a/docs/topics/null-safety.md b/docs/topics/null-safety.md
index ee3bd46a04a..e4036cfdb75 100644
--- a/docs/topics/null-safety.md
+++ b/docs/topics/null-safety.md
@@ -227,4 +227,5 @@ val intList: List<Int> = nullableList.filterNotNull()
 
 ## What's next?
 
-Learn how to [handle nullability in Java and Kotlin](java-to-kotlin-nullability-guide.md).
+* Learn how to [handle nullability in Java and Kotlin](java-to-kotlin-nullability-guide.md).
+* Learn about generic types that are [definitely non-nullable](generics.md#definitely-non-nullable-types).