Merge pull request #143 from arkivanov/update-deprecated-Router-kdocs

Updated deprecated Router kdocs
arkivanov · Jul 16, 2022 · e048b0c · e048b0c
2 parents b536e9a + 278f891
commit e048b0c
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 40 deletions.
diff --git a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/Router.kt b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/Router.kt
@@ -2,13 +2,10 @@ package com.arkivanov.decompose.router
 
 import com.arkivanov.decompose.value.Value
 
-@Deprecated(
-    message = "Use StackRouter instead",
-    replaceWith = ReplaceWith(
-        "StackRouter<C, T>",
-        "com.arkivanov.decompose.router.stack.StackRouter",
-    )
-)
+/**
+ * Deprecated. Please use Child Stack instead. See the [documentation](https://arkivanov.github.io/Decompose/child-stack/overview/).
+ */
+@Deprecated(message = "Use Child Stack instead")
 interface Router<C : Any, out T : Any> {
 
     /**

diff --git a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/RouterExt.kt b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/RouterExt.kt
@@ -4,8 +4,10 @@ import com.arkivanov.decompose.Child
 
 /**
  * A convenience method for [Router.navigate].
+ *
+ * Deprecated. Please use `Child Stack` instead. See the [documentation](https://arkivanov.github.io/Decompose/child-stack/overview/).
  */
-@Deprecated("Use StackRouter instead")
+@Deprecated("Use Child Stack instead")
 fun <C : Any> Router<C, *>.navigate(transformer: (stack: List<C>) -> List<C>) {
     navigate(transformer = transformer, onComplete = { _, _ -> })
 }
@@ -18,9 +20,11 @@ fun <C : Any> Router<C, *>.push(configuration: C) {
 /**
  * Pushes the provided [configuration] at the top of the stack.
  *
+ * Deprecated. Please use `Child Stack` instead. See the [documentation](https://arkivanov.github.io/Decompose/child-stack/overview/).
+ *
  * @param onComplete called when the navigation is finished (either synchronously or asynchronously).
  */
-@Deprecated("Use StackRouter instead")
+@Deprecated("Use Child Stack instead")
 fun <C : Any> Router<C, *>.push(configuration: C, onComplete: () -> Unit = {}) {
     navigate(transformer = { it + configuration }, onComplete = { _, _ -> onComplete() })
 }
@@ -31,8 +35,10 @@ fun <C : Any> Router<C, *>.push(configuration: C, onComplete: () -> Unit = {}) {
  * @param onComplete called when the navigation is finished (either synchronously or asynchronously).
  * The `isSuccess` argument is `true` if the stack size was greater than 1 and a component was popped,
  * `false` otherwise.
+ *
+ * Deprecated. Please use `Child Stack` instead. See the [documentation](https://arkivanov.github.io/Decompose/child-stack/overview/).
  */
-@Deprecated("Use StackRouter instead")
+@Deprecated("Use Child Stack instead")
 fun <C : Any> Router<C, *>.pop(onComplete: (isSuccess: Boolean) -> Unit = {}) {
     navigate(
         transformer = { stack -> stack.takeIf { it.size > 1 }?.dropLast(1) ?: stack },
@@ -42,20 +48,24 @@ fun <C : Any> Router<C, *>.pop(onComplete: (isSuccess: Boolean) -> Unit = {}) {
 
 /**
  * Drops the configurations at the top of the stack while the [predicate] returns `true`.
+ *
+ * Deprecated. Please use `Child Stack` instead. See the [documentation](https://arkivanov.github.io/Decompose/child-stack/overview/).
  */
 @Suppress("DeprecatedCallableAddReplaceWith")
-@Deprecated("Use StackRouter instead")
+@Deprecated("Use Child Stack instead")
 inline fun <C : Any> Router<C, *>.popWhile(crossinline predicate: (C) -> Boolean) {
     popWhile(predicate = predicate, onComplete = {})
 }
 
 /**
  * Drops the configurations at the top of the stack while the [predicate] returns true
  *
+ * Deprecated. Please use `Child Stack` instead. See the [documentation](https://arkivanov.github.io/Decompose/child-stack/overview/).
+ *
  * @param onComplete called when the navigation is finished (either synchronously or asynchronously).
  * The `isSuccess` argument is `true` if at least one component has been popped.
  */
-@Deprecated("Use StackRouter instead")
+@Deprecated("Use Child Stack instead")
 inline fun <C : Any> Router<C, *>.popWhile(
     crossinline predicate: (C) -> Boolean,
     crossinline onComplete: (isSuccess: Boolean) -> Unit,
@@ -74,9 +84,11 @@ fun <C : Any> Router<C, *>.replaceCurrent(configuration: C) {
 /**
  * Replaces the current configuration at the top of the stack with the provided [configuration].
  *
+ * Deprecated. Please use `Child Stack` instead. See the [documentation](https://arkivanov.github.io/Decompose/child-stack/overview/).
+ *
  * @param onComplete called when the navigation is finished (either synchronously or asynchronously).
  */
-@Deprecated("Use StackRouter instead")
+@Deprecated("Use Child Stack instead")
 fun <C : Any> Router<C, *>.replaceCurrent(configuration: C, onComplete: () -> Unit = {}) {
     navigate(
         transformer = { it.dropLast(1) + configuration },
@@ -92,15 +104,21 @@ fun <C : Any> Router<C, *>.bringToFront(configuration: C) {
 /**
  * Removes all components with configurations of [configuration]'s class, and adds the provided [configuration] to the top of the stack.
  * The operation is performed as one transaction. If there is already a component with the same configuration, it will not be recreated.
+ *
+ * Deprecated. Please use `Child Stack` instead. See the [documentation](https://arkivanov.github.io/Decompose/child-stack/overview/).
  */
-@Deprecated("Use StackRouter instead")
+@Deprecated("Use Child Stack instead")
 fun <C : Any> Router<C, *>.bringToFront(configuration: C, onComplete: () -> Unit = {}) {
     navigate(
         transformer = { stack -> stack.filterNot { it::class == configuration::class } + configuration },
         onComplete = { _, _ -> onComplete() },
     )
 }
 
+/**
+ * Deprecated. Please use `Child Stack` instead. See the [documentation](https://arkivanov.github.io/Decompose/child-stack/overview/).
+ */
 @Suppress("DeprecatedCallableAddReplaceWith")
-@Deprecated("Use StackRouter instead")
-val <C : Any, T : Any> Router<C, T>.activeChild: Child.Created<C, T> get() = state.value.activeChild
+@Deprecated("Use Child Stack instead")
+val <C : Any, T : Any> Router<C, T>.activeChild: Child.Created<C, T>
+    get() = state.value.activeChild
diff --git a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/RouterFactoryExt.kt b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/RouterFactoryExt.kt
@@ -8,6 +8,8 @@ import kotlin.reflect.KClass
 /**
  * Creates a new [Router].
  *
+ * Deprecated. Please use `Child Stack` instead. See the [documentation](https://arkivanov.github.io/Decompose/child-stack/overview/).
+ *
  * @param initialStack a stack of component configurations (from tail to head) that should be set if there is
  * no saved state, must be not empty and unique
  * @param configurationClass a [KClass] of the component configurations
@@ -16,13 +18,7 @@ import kotlin.reflect.KClass
  * @param childFactory a factory function that creates new child instances
  * @return a new instance of [Router]
  */
-@Deprecated(
-    message = "Use stackRouter instead",
-    replaceWith = ReplaceWith(
-        "this.stackRouter(initialStack = initialStack, configurationClass = configurationClass, key = key, handleBackButton = handleBackButton, childFactory = childFactory)",
-        "com.arkivanov.decompose.router.stack.stackRouter"
-    ),
-)
+@Deprecated(message = "Use Child Stack instead")
 fun <C : Parcelable, T : Any> ComponentContext.router(
     initialStack: () -> List<C>,
     configurationClass: KClass<out C>,
@@ -54,14 +50,11 @@ fun <C : Parcelable, T : Any> ComponentContext.router(
 
 /**
  * A convenience extension function for [ComponentContext.router].
+ *
+ * Deprecated. Please use `Child Stack` instead. See the [documentation](https://arkivanov.github.io/Decompose/child-stack/overview/).
  */
-@Deprecated(
-    message = "Use stackRouter instead",
-    replaceWith = ReplaceWith(
-        "this.stackRouter(initialStack = initialStack, key = key, handleBackButton = handleBackButton, childFactory = childFactory)",
-        "com.arkivanov.decompose.router.stack.stackRouter"
-    ),
-)
+@Suppress("DeprecatedCallableAddReplaceWith")
+@Deprecated(message = "Use Child Stack instead")
 inline fun <reified C : Parcelable, T : Any> ComponentContext.router(
     noinline initialStack: () -> List<C>,
     key: String = "DefaultRouter",
@@ -78,14 +71,11 @@ inline fun <reified C : Parcelable, T : Any> ComponentContext.router(
 
 /**
  * A convenience extension function for [ComponentContext.router].
+ *
+ * Deprecated. Please use `Child Stack` instead. See the [documentation](https://arkivanov.github.io/Decompose/child-stack/overview/).
  */
-@Deprecated(
-    message = "Use stackRouter instead",
-    replaceWith = ReplaceWith(
-        "this.stackRouter(initialConfiguration = initialConfiguration, key = key, handleBackButton = handleBackButton, childFactory = childFactory)",
-        "com.arkivanov.decompose.router.stack.stackRouter"
-    ),
-)
+@Suppress("DeprecatedCallableAddReplaceWith")
+@Deprecated(message = "Use Child Stack instead")
 inline fun <reified C : Parcelable, T : Any> ComponentContext.router(
     initialConfiguration: C,
     key: String = "DefaultRouter",

diff --git a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/stack/StackNavigator.kt b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/stack/StackNavigator.kt
@@ -7,12 +7,12 @@ interface StackNavigator<C : Any> {
      * The stack is represented as [List], where the last element is the top of the stack,
      * and the first element is the bottom of the stack. The returned stack must not be empty.
      *
-     * During the navigation process, the `StackRouter` compares the new stack of configurations with
-     * the previous one. the `StackRouter` ensures that all removed components are destroyed, and that
+     * During the navigation process, the `Child Stack` compares the new stack of configurations with
+     * the previous one. The `Child Stack` ensures that all removed components are destroyed, and that
      * there is only one component resumed at a time - the top one. All components in the back stack
      * are always either stopped or destroyed.
      *
-     * The `StackRouter` usually performs the navigation synchronously, which means that by the time
+     * The `Child Stack` usually performs the navigation synchronously, which means that by the time
      * the `navigate` method returns, the navigation is finished and all component lifecycles are
      * moved into required states. However the navigation is performed asynchronously in case of
      * recursive invocations - e.g. `pop` is called from `onResume` lifecycle callback of a