chore: add code documentation for new APIs

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
 

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 {
 
     /**

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"
 

core/src/commonMain/kotlin/pro/respawn/flowmvi/plugins/AsyncCachePlugin.kt

@@ -12,15 +12,36 @@ 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,
     start: CoroutineStart = CoroutineStart.UNDISPATCHED,
     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,

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() } }`

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

debugger/server/build.gradle.kts

@@ -42,7 +42,6 @@ tasks {
         sourceCompatibility = Config.jvmTarget.target
         targetCompatibility = Config.jvmTarget.target
     }
-
 }
 kotlin {
     jvm {

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