Added docs about initializing the navigation on the Main thread

decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/children/ChildrenFactory.kt

@@ -19,6 +19,8 @@ import kotlinx.serialization.Serializable
  * A convenience method for the main [children] method. Allows having `Serializable` navigation state [N],
  * so it's automatically saved and restored. This method can be used if the custom save/restore logic
  * is not required.
+ *
+ * **It is strongly recommended to call this method on the Main thread.**
  */
 fun <Ctx : GenericComponentContext<Ctx>, C : Any, T : Any, E : Any, N : NavState<C>, S : Any> Ctx.children(
     source: NavigationSource<E>,
@@ -74,6 +76,8 @@ fun <Ctx : GenericComponentContext<Ctx>, C : Any, T : Any, E : Any, N : NavState
  * calculates diffs between the old list of [ChildNavState] and the new one, and manipulates child
  * components as needed.
  *
+ * **It is strongly recommended to call this method on the Main thread.**
+ *
  * @param C a type of component configurations.
  * @param T a type of components.
  * @param E a type of navigation events.

decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/pages/ChildPagesFactory.kt

@@ -1,6 +1,5 @@
 package com.arkivanov.decompose.router.pages
 
-import com.arkivanov.decompose.ComponentContext
 import com.arkivanov.decompose.ExperimentalDecomposeApi
 import com.arkivanov.decompose.GenericComponentContext
 import com.arkivanov.decompose.router.children.ChildNavState
@@ -19,6 +18,8 @@ import kotlinx.serialization.Serializable
  * Initializes and manages a list of components with one selected (active) component.
  * The list can be empty.
  *
+ * **It is strongly recommended to call this method on the Main thread.**
+ *
  * @param source a source of navigation events.
  * @param serializer an optional [KSerializer] to be used for serializing and deserializing configurations.
  * If `null` then the navigation state will not be preserved.
@@ -85,6 +86,8 @@ private class SerializablePages<out C : Any>(
  * Initializes and manages a list of components with one selected (active) component.
  * The list can be empty.
  *
+ * **It is strongly recommended to call this method on the Main thread.**
+ *
  * @param source a source of navigation events.
  * @param initialPages an initial state of Child Pages that should be set
  * if there is no saved state. See [Pages] for more information.

decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/slot/ChildSlotFactory.kt

@@ -16,6 +16,8 @@ import kotlinx.serialization.KSerializer
  * Initializes and manages a slot for one child component.
  * The child component can be either active or dismissed (destroyed).
  *
+ * **It is strongly recommended to call this method on the Main thread.**
+ *
  * @param source a source of navigation events.
  * @param serializer an optional [KSerializer] to be used for serializing and deserializing configurations.
  * If `null` then the navigation state will not be preserved.
@@ -61,6 +63,8 @@ fun <Ctx : GenericComponentContext<Ctx>, C : Any, T : Any> Ctx.childSlot(
  * Initializes and manages a slot for one child component.
  * The child component can be either active or dismissed (destroyed).
  *
+ * **It is strongly recommended to call this method on the Main thread.**
+ *
  * @param source a source of navigation events.
  * @param key a key of the slot, must be unique within the parent (hosting) component.
  * @param saveConfiguration a function that saves the provided configuration into [SerializableContainer].

decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/stack/ChildStackFactory.kt

@@ -17,6 +17,8 @@ import kotlinx.serialization.builtins.ListSerializer
 /**
  * Initializes and manages a stack of components.
  *
+ * **It is strongly recommended to call this method on the Main thread.**
+ *
  * @param source a source of navigation events.
  * @param serializer an optional [KSerializer] to be used for serializing and deserializing configurations.
  * If `null` then the navigation state will not be preserved.
@@ -60,6 +62,8 @@ fun <Ctx: GenericComponentContext<Ctx>, C : Any, T : Any> Ctx.childStack(
 
 /**
  * A convenience extension function for [ComponentContext.childStack].
+ *
+ * **It is strongly recommended to call this method on the Main thread.**
  */
 fun <Ctx : GenericComponentContext<Ctx>, C : Any, T : Any> Ctx.childStack(
     source: NavigationSource<StackNavigation.Event<C>>,
@@ -81,6 +85,8 @@ fun <Ctx : GenericComponentContext<Ctx>, C : Any, T : Any> Ctx.childStack(
 /**
  * Initializes and manages a stack of components.
  *
+ * **It is strongly recommended to call this method on the Main thread.**
+ *
  * @param source a source of navigation events.
  * @param initialStack a stack of component configurations (ordered from tail to head) that should be set
  * if there is no saved state, must be not empty and unique.

docs/navigation/overview.md

@@ -40,9 +40,9 @@ Please make sure you [setup](https://github.com/Kotlin/kotlinx.serialization#set
 
 ## Navigation and the main thread
 
-The navigation API is thread-safe, technically the navigation can be performed on any thread. However, it's strongly recommended to perform the navigation on the Main thread. Since the navigation is performed synchronously, Decompose instantiates components and calls lifecycle callbacks on the current thread. Navigating on a background thread may cause unexpected behaviour.
+The navigation API is thread-safe, technically the navigation can be performed on any thread. However, it's strongly recommended to initialize and perform the navigation on the Main thread. Since the navigation is performed synchronously, Decompose instantiates components and calls lifecycle callbacks on the current thread. Navigating on a background thread may cause unexpected behaviour.
 
 !!!warning
-    Always perform the navigation on the Main thread.
+    Always initialize and perform the navigation on the Main thread.
 
 Decompose tries its best to detect when the navigation is performed on a non-main thread. When it happens, Decompose calls the special error handler - `onDecomposeError`. By default, it prints the exception to logs,  however you can override the default behaviour by providing your own handler.