Merge pull request #19 from soil-kt/kdoc

Add a KDoc comments for the soil.query.compose.runtime package

soil-query-compose-runtime/src/commonMain/kotlin/soil/query/compose/runtime/Await.kt

@@ -19,7 +19,6 @@ import soil.query.compose.QueryRefreshErrorObject
 import soil.query.compose.QuerySuccessObject
 import soil.query.internal.uuid
 
-
 @Composable
 inline fun <T> Await(
  state: Loadable<T>,
@@ -43,6 +42,18 @@ inline fun <T> Await(
  }
 }
 
+/**
+ * Await for a [QueryModel] to be fulfilled.
+ *
+ * The content will be displayed when the query is fulfilled.
+ * The await will be managed by the [AwaitHost].
+ *
+ * @param T Type of data to retrieve.
+ * @param state The [QueryModel] to await.
+ * @param key The key to identify the await.
+ * @param host The [AwaitHost] to manage the await. By default, it uses the [LocalAwaitHost].
+ * @param content The content to display when the query is fulfilled.
+ */
 @Composable
 inline fun <T> Await(
  state: QueryModel<T>,
@@ -64,6 +75,20 @@ inline fun <T> Await(
  }
 }
 
+/**
+ * Await for two [QueryModel] to be fulfilled.
+ *
+ * The content will be displayed when the queries are fulfilled.
+ * The await will be managed by the [AwaitHost].
+ *
+ * @param T1 Type of data to retrieve.
+ * @param T2 Type of data to retrieve.
+ * @param state1 The first [QueryModel] to await.
+ * @param state2 The second [QueryModel] to await.
+ * @param key The key to identify the await.
+ * @param host The [AwaitHost] to manage the await. By default, it uses the [LocalAwaitHost].
+ * @param content The content to display when the queries are fulfilled.
+ */
 @Composable
 inline fun <T1, T2> Await(
  state1: QueryModel<T1>,
@@ -88,6 +113,22 @@ inline fun <T1, T2> Await(
  }
 }
 
+/**
+ * Await for three [QueryModel] to be fulfilled.
+ *
+ * The content will be displayed when the queries are fulfilled.
+ * The await will be managed by the [AwaitHost].
+ *
+ * @param T1 Type of data to retrieve.
+ * @param T2 Type of data to retrieve.
+ * @param T3 Type of data to retrieve.
+ * @param state1 The first [QueryModel] to await.
+ * @param state2 The second [QueryModel] to await.
+ * @param state3 The third [QueryModel] to await.
+ * @param key The key to identify the await.
+ * @param host The [AwaitHost] to manage the await. By default, it uses the [LocalAwaitHost].
+ * @param content The content to display when the queries are fulfilled.
+ */
 @Composable
 inline fun <T1, T2, T3> Await(
  state1: QueryModel<T1>,
@@ -115,6 +156,24 @@ inline fun <T1, T2, T3> Await(
  }
 }
 
+/**
+ * Await for four [QueryModel] to be fulfilled.
+ *
+ * The content will be displayed when the queries are fulfilled.
+ * The await will be managed by the [AwaitHost].
+ *
+ * @param T1 Type of data to retrieve.
+ * @param T2 Type of data to retrieve.
+ * @param T3 Type of data to retrieve.
+ * @param T4 Type of data to retrieve.
+ * @param state1 The first [QueryModel] to await.
+ * @param state2 The second [QueryModel] to await.
+ * @param state3 The third [QueryModel] to await.
+ * @param state4 The fourth [QueryModel] to await.
+ * @param key The key to identify the await.
+ * @param host The [AwaitHost] to manage the await. By default, it uses the [LocalAwaitHost].
+ * @param content The content to display when the queries are fulfilled.
+ */
 @Composable
 inline fun <T1, T2, T3, T4> Await(
  state1: QueryModel<T1>,
@@ -145,6 +204,26 @@ inline fun <T1, T2, T3, T4> Await(
  }
 }
 
+/**
+ * Await for five [QueryModel] to be fulfilled.
+ *
+ * The content will be displayed when the queries are fulfilled.
+ * The await will be managed by the [AwaitHost].
+ *
+ * @param T1 Type of data to retrieve.
+ * @param T2 Type of data to retrieve.
+ * @param T3 Type of data to retrieve.
+ * @param T4 Type of data to retrieve.
+ * @param T5 Type of data to retrieve.
+ * @param state1 The first [QueryModel] to await.
+ * @param state2 The second [QueryModel] to await.
+ * @param state3 The third [QueryModel] to await.
+ * @param state4 The fourth [QueryModel] to await.
+ * @param state5 The fifth [QueryModel] to await.
+ * @param key The key to identify the await.
+ * @param host The [AwaitHost] to manage the await. By default, it uses the [LocalAwaitHost].
+ * @param content The content to display when the queries are fulfilled.
+ */
 @Composable
 inline fun <T1, T2, T3, T4, T5> Await(
  state1: QueryModel<T1>,
@@ -178,6 +257,16 @@ inline fun <T1, T2, T3, T4, T5> Await(
  }
 }
 
+/**
+ * Await for [QueryModel] to be fulfilled.
+ *
+ * This function is part of the [Await].
+ * It is used to handle the [QueryModel] state and display the content when the query is fulfilled.
+ *
+ * @param T Type of data to retrieve.
+ * @param state The [QueryModel] to await.
+ * @param content The content to display when the query is fulfilled.
+ */
 @Composable
 fun <T> AwaitHandler(
  state: QueryModel<T>,
@@ -202,6 +291,9 @@ fun <T> AwaitHandler(
  }
 }
 
+/**
+ * Returns true if the [QueryModel] is awaited.
+ */
 fun QueryModel<*>.isAwaited(): Boolean {
  return isPending
  || (isFailure && fetchStatus == QueryFetchStatus.Fetching)

soil-query-compose-runtime/src/commonMain/kotlin/soil/query/compose/runtime/AwaitHost.kt

@@ -6,17 +6,37 @@ package soil.query.compose.runtime
 import androidx.compose.runtime.Stable
 import androidx.compose.runtime.compositionLocalOf
 
+/**
+ * A host to manage the await state of a key.
+ *
+ * @see Await
+ */
 @Stable
 interface AwaitHost {
 
+ /**
+ * Returns the set of keys that are awaited.
+ */
  val keys: Set<Any>
 
+ /**
+ * Returns `true` if the key is awaited.
+ */
  operator fun get(key: Any): Boolean
 
+ /**
+ * Sets the key to be awaited or not.
+ */
  operator fun set(key: Any, isAwaited: Boolean)
 
+ /**
+ * Removes the key from the awaited set.
+ */
  fun remove(key: Any)
 
+ /**
+ * A noop implementation of [AwaitHost].
+ */
  companion object Noop : AwaitHost {
 
  override val keys: Set<Any> = emptySet()
@@ -29,6 +49,9 @@ interface AwaitHost {
  }
 }
 
+/**
+ * CompositionLocal for [AwaitHost].
+ */
 val LocalAwaitHost = compositionLocalOf<AwaitHost> {
  AwaitHost
 }

soil-query-compose-runtime/src/commonMain/kotlin/soil/query/compose/runtime/Catch.kt

@@ -46,6 +46,13 @@ fun <T : Throwable> Catch(
  }
 }
 
+/**
+ * Catch for a [QueryModel] to be rejected.
+ *
+ * @param state The [QueryModel] to catch.
+ * @param isEnabled Whether to catch the error.
+ * @param content The content to display when the query is rejected. By default, it [throws][CatchScope.Throw] the error.
+ */
 @Composable
 fun Catch(
  state: QueryModel<*>,
@@ -60,6 +67,14 @@ fun Catch(
  )
 }
 
+/**
+ * Catch for any [QueryModel]s to be rejected.
+ *
+ * @param state1 The first [QueryModel] to catch.
+ * @param state2 The second [QueryModel] to catch.
+ * @param isEnabled Whether to catch the error.
+ * @param content The content to display when the query is rejected. By default, it [throws][CatchScope.Throw] the error.
+ */
 @Composable
 fun Catch(
  state1: QueryModel<*>,
@@ -76,6 +91,15 @@ fun Catch(
  )
 }
 
+/**
+ * Catch for any [QueryModel]s to be rejected.
+ *
+ * @param state1 The first [QueryModel] to catch.
+ * @param state2 The second [QueryModel] to catch.
+ * @param state3 The third [QueryModel] to catch.
+ * @param isEnabled Whether to catch the error.
+ * @param content The content to display when the query is rejected. By default, it [throws][CatchScope.Throw] the error.
+ */
 @Composable
 fun Catch(
  state1: QueryModel<*>,
@@ -94,6 +118,13 @@ fun Catch(
  )
 }
 
+/**
+ * Catch for any [QueryModel]s to be rejected.
+ *
+ * @param states The [QueryModel]s to catch.
+ * @param isEnabled Whether to catch the error.
+ * @param content The content to display when the query is rejected. By default, it [throws][CatchScope.Throw] the error.
+ */
 @Composable
 fun Catch(
  vararg states: QueryModel<*>,
@@ -108,6 +139,14 @@ fun Catch(
  )
 }
 
+/**
+ * Catch for a [QueryModel] to be rejected.
+ *
+ * @param state The [QueryModel] to catch.
+ * @param filterIsInstance A function to filter the error.
+ * @param isEnabled Whether to catch the error.
+ * @param content The content to display when the query is rejected. By default, it [throws][CatchScope.Throw] the error.
+ */
 @Composable
 fun <T : Throwable> Catch(
  state: QueryModel<*>,
@@ -121,6 +160,15 @@ fun <T : Throwable> Catch(
  }
 }
 
+/**
+ * Catch for any [QueryModel]s to be rejected.
+ *
+ * @param state1 The first [QueryModel] to catch.
+ * @param state2 The second [QueryModel] to catch.
+ * @param filterIsInstance A function to filter the error.
+ * @param isEnabled Whether to catch the error.
+ * @param content The content to display when the query is rejected. By default, it [throws][CatchScope.Throw] the error.
+ */
 @Composable
 fun <T : Throwable> Catch(
  state1: QueryModel<*>,
@@ -138,6 +186,16 @@ fun <T : Throwable> Catch(
  }
 }
 
+/**
+ * Catch for any [QueryModel]s to be rejected.
+ *
+ * @param state1 The first [QueryModel] to catch.
+ * @param state2 The second [QueryModel] to catch.
+ * @param state3 The third [QueryModel] to catch.
+ * @param filterIsInstance A function to filter the error.
+ * @param isEnabled Whether to catch the error.
+ * @param content The content to display when the query is rejected. By default, it [throws][CatchScope.Throw] the error.
+ */
 @Composable
 fun <T : Throwable> Catch(
  state1: QueryModel<*>,
@@ -156,6 +214,14 @@ fun <T : Throwable> Catch(
  }
 }
 
+/**
+ * Catch for any [QueryModel]s to be rejected.
+ *
+ * @param states The [QueryModel]s to catch.
+ * @param filterIsInstance A function to filter the error.
+ * @param isEnabled Whether to catch the error.
+ * @param content The content to display when the query is rejected. By default, it [throws][CatchScope.Throw] the error.
+ */
 @Composable
 fun <T : Throwable> Catch(
  vararg states: QueryModel<*>,
@@ -172,8 +238,18 @@ fun <T : Throwable> Catch(
  }
 }
 
-
+/**
+ * A scope for handling error content within the [Catch] function.
+ */
 object CatchScope {
+
+ /**
+ * Throw propagates the caught exception to a [CatchThrowHost].
+ *
+ * @param error The caught exception.
+ * @param key The key to identify the caught exception.
+ * @param host The [CatchThrowHost] to manage the caught exception. By default, it uses the [LocalCatchThrowHost].
+ */
  @Composable
  fun Throw(
  error: Throwable,

soil-query-compose-runtime/src/commonMain/kotlin/soil/query/compose/runtime/CatchThrowHost.kt

@@ -6,17 +6,37 @@ package soil.query.compose.runtime
 import androidx.compose.runtime.Stable
 import androidx.compose.runtime.compositionLocalOf
 
+/**
+ * A host to manage the caught errors of a key.
+ *
+ * @see Catch
+ */
 @Stable
 interface CatchThrowHost {
 
+ /**
+ * Returns the set of keys that have caught errors.
+ */
  val keys: Set<Any>
 
+ /**
+ * Returns the caught error of the key.
+ */
  operator fun get(key: Any): Throwable?
 
+ /**
+ * Sets the caught error of the key.
+ */
  operator fun set(key: Any, error: Throwable)
 
+ /**
+ * Removes the caught error of the key.
+ */
  fun remove(key: Any)
 
+ /**
+ * A noop implementation of [CatchThrowHost].
+ */
  companion object Noop : CatchThrowHost {
 
  override val keys: Set<Any> = emptySet()
@@ -29,6 +49,9 @@ interface CatchThrowHost {
  }
 }
 
+/**
+ * CompositionLocal for [CatchThrowHost].
+ */
 val LocalCatchThrowHost = compositionLocalOf<CatchThrowHost> {
  CatchThrowHost
 }