Add some guidance for when to use extension functions.
PiperOrigin-RevId: 613261754
Change-Id: Id2af0804eda45f64895fce400e07d2cdcc805469
diff --git a/docs/api_guidelines/kotlin.md b/docs/api_guidelines/kotlin.md
index d9ebe4a..0ba1c0d 100644
--- a/docs/api_guidelines/kotlin.md
+++ b/docs/api_guidelines/kotlin.md
@@ -335,6 +335,52 @@
matching signature will be added in the future. As such, Jetpack libraries
should avoid adding extension functions on platform classes.
+### Extension functions related to classes in the same module or file
+
+When the core type is in Java, one good use for extension functions is to create
+more Kotlin friendly versions of the API.
+
+```java
+public class MyClass {
+ public void addMyListener(Executor e, Consumer<Data> listener) { ... }
+ public void removeMyListener(Consumer<Data> listener) { ... }
+}
+```
+
+```kotlin
+fun MyClass.dataFlow(): Flow<Data>
+```
+
+When the core type is in Kotlin, extension functions may or may not be a good
+fit for the API. Ask if the extension is part of the core abstraction or a new
+layer of abstraction. One example of a new layer of abstraction is using a new
+dependency that does not otherwise interact with the core class. Another example
+is an abstraction that stands on its own such as a `Comparator` that implements
+a non-canonical ordering.
+
+In general when adding extension functions, consider splitting them across
+different files and naming the Java version of the files related to the use case
+as opposed to putting everything in one file and using a `Util` suffix.
+
+```kotlin {.bad}
+@file:JvmName("WindowSizeClassUtil")
+
+fun Set<WindowSizeClass>.widestClass() : WindowSizeClass { ... }
+
+fun WindowSizeClass.scoreWithinWidthDp(widthDp: Int) { ... }
+```
+
+```kotlin
+@file:JvmName("WindowSizeClassSelector")
+
+fun Set<WindowSizeClass>.widestClass() : WindowSizeClass { ... }
+
+// In another file
+@file:JvmName("WindowSizeClassScoreCalculator")
+
+fun WindowSizeClass.scoreWithinWidthDp(widthDp: Int) { ... }
+```
+
### Function parameters order {#kotlin-params-order}
In Kotlin function parameters can have default values, which are used when you
