Updated StateKeeper and InstanceKeeper docs

docs/component/instance-retaining.md

@@ -1,6 +1,6 @@
-# Instance retaining
+# Instance retaining (aka ViewModel)
 
-Sometimes it might be necessary to preserve state or data in a component when it gets destroyed. This commonly used in Android when configuration changes occur. The `ComponentContext` interface extends the `InstanceKeeperOwner` interface, which provides the `InstanceKeeper` - a multiplatform abstraction for instances retaining. It is provided by [Essenty](https://github.com/arkivanov/Essenty) library (from the same author).
+Sometimes it might be necessary to keep an object in memory (retain the instance) in a component when it gets recreated. This commonly used in Android when configuration changes occur. Many Android developers are used to AndroidX `ViewModel`, however Decompose takes a different approach. The `ComponentContext` interface extends the `InstanceKeeperOwner` interface, which provides the `InstanceKeeper` - a multiplatform abstraction for instances retaining. It is provided by [Essenty](https://github.com/arkivanov/Essenty) library (from the same author).
 
 The `decompose` module adds Essenty's `instance-keeper` module as `api` dependency, so you don't need to explicitly add it to your project. Please familiarise yourself with Essenty library, especially with the `InstanceKeeper`.
 
@@ -18,8 +18,10 @@ class SomeComponent(
     private val someLogic = instanceKeeper.getOrCreate(::SomeLogic)
 
     /*
-     * Instances of this class will be retained.
-     * ⚠️ Pay attention to not leak any dependencies.
+     * Instances of this class will be retained (not destroyed on configuration changes).
+     * This is equivalent to AndroidX ViewModel.
+     * ⚠️ Pay attention to not leak any dependencies, 
+     * e.g. don't make this class `inner`, and don't pass dependencies like Activity Context into it.
      */
     private class SomeLogic : InstanceKeeper.Instance {
         override fun onDestroy() {

docs/component/state-preservation.md

@@ -1,6 +1,6 @@
-# State preservation
+# State preservation (aka SavedStateHandle)
 
-Sometimes it might be necessary to preserve state or data in a component when it gets destroyed (e.g. killed by the system). A very common use case is Android Activity recreation due to configuration changes, or process death on Android or iOS. The `ComponentContext` interface extends the `StateKeeperOwner` interface, which provides the `StateKeeper` API - a multiplatform abstraction for state preservation. It is provided by [Essenty](https://github.com/arkivanov/Essenty) library (from the same author).
+Sometimes it might be necessary to preserve some persistent state or data in a component when it gets destroyed (e.g. killed by the system). A very common use case is Android Activity recreation due to configuration changes, or process death on Android or iOS. Many Android developers are used to AndroidX `SavedStateHandle`, however Decompose takes a different approach. The `ComponentContext` interface extends the `StateKeeperOwner` interface, which provides the `StateKeeper` API - a multiplatform abstraction for state preservation. It is provided by [Essenty](https://github.com/arkivanov/Essenty) library (from the same author).
 
 The `decompose` module adds Essenty's `state-keeper` module as `api` dependency, so you don't need to explicitly add it to your project. Please familiarise yourself with Essenty library, especially with the `StateKeeper` API.
 
@@ -16,13 +16,16 @@ class SomeComponent(
     componentContext: ComponentContext
 ) : ComponentContext by componentContext {
 
+    // Either restore the previously saved state or create a new (initial) one
     private var state: State = stateKeeper.consume(key = "SAVED_STATE", strategy = State.serializer()) ?: State()
 
     init {
-        stateKeeper.register(key = "SAVED_STATE", strategy = State.serializer()) { state }
+        stateKeeper.register(key = "SAVED_STATE", strategy = State.serializer()) {
+            state // Called when it's time to save the state
+        }
     }
 
-    @Serializable
+    @Serializable // Comes from kotlinx-serialization
     private class State(val someValue: Int = 0)
 }
 ```

mkdocs.yml

@@ -25,8 +25,8 @@ nav:
     - Overview: component/overview.md
     - Child components: component/child-components.md
     - Lifecycle: component/lifecycle.md
-    - State preservation: component/state-preservation.md
-    - Instance retaining: component/instance-retaining.md
+    - State preservation (aka SavedStateHandle): component/state-preservation.md
+    - Instance retaining (aka ViewModel): component/instance-retaining.md
     - Back button: component/back-button.md
     - Scoping jobs and subscriptions: component/scopes.md
     - Custom ComponentContext: component/custom-component-context.md