From 2ffafaee79d73f7a4cbb52c4f2250a8e536bdd51 Mon Sep 17 00:00:00 2001
From: Steven Schoen <steven@stevenschoen.com>
Date: Fri, 29 Sep 2023 23:19:21 -0400
Subject: [PATCH] Add kdoc to ControllerChangeHandler::removesFromViewOnPush
 (#688)

---
 .../conductor/ControllerChangeHandler.kt      | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/conductor/src/main/java/com/bluelinelabs/conductor/ControllerChangeHandler.kt b/conductor/src/main/java/com/bluelinelabs/conductor/ControllerChangeHandler.kt
index e27f015e..61ba094d 100644
--- a/conductor/src/main/java/com/bluelinelabs/conductor/ControllerChangeHandler.kt
+++ b/conductor/src/main/java/com/bluelinelabs/conductor/ControllerChangeHandler.kt
@@ -23,6 +23,29 @@ abstract class ControllerChangeHandler {
    */
   open val isReusable: Boolean = false
 
+  /**
+   * Returns whether or not this handler removes the `from` view from the container when performing a push.
+   *
+   * If this is true:
+   * - This handler's implementation of [performChange] should remove `from` from `container`
+   *   before calling `changeListener.onChangeCompleted()`
+   * - When a controller is pushed, the previous controller will stay attached and its view will remain created
+   * - When a view is recreated (e.g. after a configuration change), any controllers underneath a transaction
+   *   using this handler will have their view recreated and attached, even though they're not the top-most
+   *   controller
+   *
+   * If this is false:
+   * - This handler's implementation of [performChange] should only remove `from` from `container`
+   *   when `isPush` is false
+   * - When a controller is pushed, the previous controller will be detached and its view will be destroyed
+   *
+   * If a controller pushed onto the backstack will completely cover the previous controller,
+   * using a change handler with [removesFromViewOnPush] true should result in no visual interruption
+   * to the user, while allowing the previous controller's view to be destroyed to reclaim resources.
+   * If instead, the previous controller should still be visible after the new controller is pushed,
+   * using a change handler with [removesFromViewOnPush] false will keep the previous controller's
+   * view in the view hierarchy, where it can still be seen (and even interacted with).
+   */
   open val removesFromViewOnPush: Boolean = true
 
   private var hasBeenUsed = false