From a61c124bfc8765f94c7a709cfc0add4ee2f989a0 Mon Sep 17 00:00:00 2001
From: Nek-12 <vaizin.nikita@gmail.com>
Date: Tue, 5 Nov 2024 19:37:13 +0100
Subject: [PATCH] chore: add code documentation for new APIs

---
 .../pro/respawn/flowmvi/api/ImmutableStore.kt | 14 ++++++++++++-
 .../api/lifecycle/ImmutableStoreLifecycle.kt  |  9 ++++++++
 .../respawn/flowmvi/modules/PipelineModule.kt | 10 ++++-----
 .../flowmvi/plugins/AsyncCachePlugin.kt       | 21 +++++++++++++++++++
 .../respawn/flowmvi/plugins/DeinitPlugin.kt   |  2 +-
 .../flowmvi/test/store/StoreLaunchTest.kt     |  1 -
 debugger/server/build.gradle.kts              |  1 -
 .../test/plugin/TestPipelineContext.kt        |  3 ---
 8 files changed, 49 insertions(+), 12 deletions(-)

diff --git a/core/src/commonMain/kotlin/pro/respawn/flowmvi/api/ImmutableStore.kt b/core/src/commonMain/kotlin/pro/respawn/flowmvi/api/ImmutableStore.kt
index a762b3ea..c3f7a321 100644
--- a/core/src/commonMain/kotlin/pro/respawn/flowmvi/api/ImmutableStore.kt
+++ b/core/src/commonMain/kotlin/pro/respawn/flowmvi/api/ImmutableStore.kt
@@ -4,6 +4,7 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.flow.Flow
 import pro.respawn.flowmvi.api.lifecycle.ImmutableStoreLifecycle
+import pro.respawn.flowmvi.api.lifecycle.StoreLifecycle
 
 /**
  * A [Store] that does not allow sending intents.
@@ -20,10 +21,21 @@ public interface ImmutableStore<out S : MVIState, in I : MVIIntent, out A : MVIA
     /**
      * Starts store intent processing in a new coroutine in the given [scope].
      * Intents are processed as long as the parent scope is active.
+     *
      * **Starting store processing when it is already started will result in an exception.**
+     *
      * Although not always needed, store can be launched multiple times,
      * assuming you cancel the job used before or call [Store.close].
-     * @return a [Job] that the store is running on that can be cancelled later. [Store.close] will cancel that job.
+     *
+     * Returns an [ImmutableStoreLifecycle] that the store is running on that can be cancelled later.
+     * A mutable version [Store] returns a mutable [StoreLifecycle] that can be used to stop the store.
+     *
+     * The [Store] also implements [StoreLifecycle] but there is an **important** distinction between the one returned
+     * by this method and the [Store] itself. The returned reference only tracks the lifecycle resulting from this call,
+     * while the [Store] tracks **all** starts and stops as a single lifecycle.
+     *
+     * For example, waiting for startup or closing the returned lifecycle multiple times is a no-op, while the store
+     * object itself will have the opposite behavior and wait for the next [start] call.
      */
     public fun start(scope: CoroutineScope): ImmutableStoreLifecycle
 
diff --git a/core/src/commonMain/kotlin/pro/respawn/flowmvi/api/lifecycle/ImmutableStoreLifecycle.kt b/core/src/commonMain/kotlin/pro/respawn/flowmvi/api/lifecycle/ImmutableStoreLifecycle.kt
index e2ad4549..d22b3ac4 100644
--- a/core/src/commonMain/kotlin/pro/respawn/flowmvi/api/lifecycle/ImmutableStoreLifecycle.kt
+++ b/core/src/commonMain/kotlin/pro/respawn/flowmvi/api/lifecycle/ImmutableStoreLifecycle.kt
@@ -1,7 +1,16 @@
 package pro.respawn.flowmvi.api.lifecycle
 
+import pro.respawn.flowmvi.api.ImmutableStore
 import pro.respawn.flowmvi.api.Store
 
+/**
+ * A lifecycle of a [Store]. This handle allows syncing operations with the events of the store's startup and shutdown.
+ *
+ * * [Store] implements [StoreLifecycle]
+ * * [ImmutableStore] implements [ImmutableStoreLifecycle]
+ *
+ * This is also returned from [Store.start]
+ */
 public interface ImmutableStoreLifecycle {
 
     /**
diff --git a/core/src/commonMain/kotlin/pro/respawn/flowmvi/modules/PipelineModule.kt b/core/src/commonMain/kotlin/pro/respawn/flowmvi/modules/PipelineModule.kt
index bd4aa8a0..49f89276 100644
--- a/core/src/commonMain/kotlin/pro/respawn/flowmvi/modules/PipelineModule.kt
+++ b/core/src/commonMain/kotlin/pro/respawn/flowmvi/modules/PipelineModule.kt
@@ -60,11 +60,11 @@ internal inline fun <S : MVIState, I : MVIIntent, A : MVIAction, T> T.launchPipe
         private val pipelineName = CoroutineName(toString())
 
         override val coroutineContext = parent.coroutineContext +
-                config.coroutineContext +
-                pipelineName +
-                job +
-                handler +
-                this
+            config.coroutineContext +
+            pipelineName +
+            job +
+            handler +
+            this
 
         override fun toString(): String = "${config.name.orEmpty()}PipelineContext"
 
diff --git a/core/src/commonMain/kotlin/pro/respawn/flowmvi/plugins/AsyncCachePlugin.kt b/core/src/commonMain/kotlin/pro/respawn/flowmvi/plugins/AsyncCachePlugin.kt
index a77155d1..54ee6c0d 100644
--- a/core/src/commonMain/kotlin/pro/respawn/flowmvi/plugins/AsyncCachePlugin.kt
+++ b/core/src/commonMain/kotlin/pro/respawn/flowmvi/plugins/AsyncCachePlugin.kt
@@ -12,8 +12,19 @@ import pro.respawn.flowmvi.dsl.StoreBuilder
 import kotlin.coroutines.CoroutineContext
 import kotlin.coroutines.EmptyCoroutineContext
 
+/**
+ * Alias for [Deferred.await]
+ */
 public suspend operator fun <T> Deferred<T>.invoke(): T = await()
 
+/**
+ * Create a new [CachedValue] but run the [init] in an asynchronous way and return a [Deferred] that can be used
+ * to await the value
+ * @return A [CachedValue] granting access to the value returned from [init]
+ * @see cached
+ * @see cachePlugin
+ * @see Deferred
+ */
 @FlowMVIDSL
 public inline fun <T, S : MVIState, I : MVIIntent, A : MVIAction> asyncCached(
     context: CoroutineContext = EmptyCoroutineContext,
@@ -21,6 +32,16 @@ public inline fun <T, S : MVIState, I : MVIIntent, A : MVIAction> asyncCached(
     crossinline init: suspend PipelineContext<S, I, A>.() -> T,
 ): CachedValue<Deferred<T>, S, I, A> = cached { async(context, start) { init() } }
 
+/**
+ * Install a new [cachePlugin] that will run the [init] in an asynchronous way and return a [Deferred] that can be used
+ * to await the value.
+ *
+ * @return A [CachedValue] granting access to the value returned from [init]
+ * @see cached
+ * @see cachePlugin
+ * @see asyncCached
+ * @see Deferred
+ */
 @FlowMVIDSL
 public inline fun <T, S : MVIState, I : MVIIntent, A : MVIAction> StoreBuilder<S, I, A>.asyncCache(
     context: CoroutineContext = EmptyCoroutineContext,
diff --git a/core/src/commonMain/kotlin/pro/respawn/flowmvi/plugins/DeinitPlugin.kt b/core/src/commonMain/kotlin/pro/respawn/flowmvi/plugins/DeinitPlugin.kt
index b8acdeaf..59ba7030 100644
--- a/core/src/commonMain/kotlin/pro/respawn/flowmvi/plugins/DeinitPlugin.kt
+++ b/core/src/commonMain/kotlin/pro/respawn/flowmvi/plugins/DeinitPlugin.kt
@@ -4,9 +4,9 @@ import pro.respawn.flowmvi.api.FlowMVIDSL
 import pro.respawn.flowmvi.api.MVIAction
 import pro.respawn.flowmvi.api.MVIIntent
 import pro.respawn.flowmvi.api.MVIState
+import pro.respawn.flowmvi.api.StorePlugin
 import pro.respawn.flowmvi.dsl.StoreBuilder
 import pro.respawn.flowmvi.dsl.plugin
-import pro.respawn.flowmvi.api.StorePlugin
 
 /**
  * Alias for [StorePlugin.onStop] callback or `plugin { onStop { block() } }`
diff --git a/core/src/jvmTest/kotlin/pro/respawn/flowmvi/test/store/StoreLaunchTest.kt b/core/src/jvmTest/kotlin/pro/respawn/flowmvi/test/store/StoreLaunchTest.kt
index 8d5d3f49..f55682ce 100644
--- a/core/src/jvmTest/kotlin/pro/respawn/flowmvi/test/store/StoreLaunchTest.kt
+++ b/core/src/jvmTest/kotlin/pro/respawn/flowmvi/test/store/StoreLaunchTest.kt
@@ -7,7 +7,6 @@ import io.kotest.matchers.collections.shouldBeSingleton
 import io.kotest.matchers.shouldBe
 import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.cancel
-import kotlinx.coroutines.cancelAndJoin
 import kotlinx.coroutines.coroutineScope
 import kotlinx.coroutines.supervisorScope
 import kotlinx.coroutines.withTimeout
diff --git a/debugger/server/build.gradle.kts b/debugger/server/build.gradle.kts
index 1f08a5ad..cb28e9ac 100644
--- a/debugger/server/build.gradle.kts
+++ b/debugger/server/build.gradle.kts
@@ -42,7 +42,6 @@ tasks {
         sourceCompatibility = Config.jvmTarget.target
         targetCompatibility = Config.jvmTarget.target
     }
-
 }
 kotlin {
     jvm {
diff --git a/test/src/commonMain/kotlin/pro/respawn/flowmvi/test/plugin/TestPipelineContext.kt b/test/src/commonMain/kotlin/pro/respawn/flowmvi/test/plugin/TestPipelineContext.kt
index 4f727346..7dcc862d 100644
--- a/test/src/commonMain/kotlin/pro/respawn/flowmvi/test/plugin/TestPipelineContext.kt
+++ b/test/src/commonMain/kotlin/pro/respawn/flowmvi/test/plugin/TestPipelineContext.kt
@@ -4,9 +4,6 @@ package pro.respawn.flowmvi.test.plugin
 
 import kotlinx.atomicfu.atomic
 import kotlinx.coroutines.Job
-import kotlinx.coroutines.cancel
-import kotlinx.coroutines.cancelAndJoin
-import kotlinx.coroutines.job
 import kotlinx.coroutines.launch
 import pro.respawn.flowmvi.api.DelicateStoreApi
 import pro.respawn.flowmvi.api.ExperimentalStoreApi