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

soil-query-compose/src/commonMain/kotlin/soil/query/compose/InfiniteQueryComposable.kt

@@ -15,6 +15,15 @@ import soil.query.QueryClient
 import soil.query.QueryState
 import soil.query.QueryStatus
 
+/**
+ * Remember a [InfiniteQueryObject] and subscribes to the query state of [key].
+ *
+ * @param T Type of data to retrieve.
+ * @param S Type of parameter.
+ * @param key The [InfiniteQueryKey] for managing [query][soil.query.Query] associated with [id][soil.query.InfiniteQueryId].
+ * @param client The [QueryClient] to resolve [key]. By default, it uses the [LocalSwrClient].
+ * @return A [InfiniteQueryObject] each the query state changed.
+ */
 @Composable
 fun <T, S> rememberInfiniteQuery(
  key: InfiniteQueryKey<T, S>,
@@ -30,6 +39,16 @@ fun <T, S> rememberInfiniteQuery(
  }
 }
 
+/**
+ * Remember a [InfiniteQueryObject] and subscribes to the query state of [key].
+ *
+ * @param T Type of data to retrieve.
+ * @param S Type of parameter.
+ * @param key The [InfiniteQueryKey] for managing [query][soil.query.Query] associated with [id][soil.query.InfiniteQueryId].
+ * @param select A function to select data from [QueryChunks].
+ * @param client The [QueryClient] to resolve [key]. By default, it uses the [LocalSwrClient].
+ * @return A [InfiniteQueryObject] with selected data each the query state changed.
+ */
 @Composable
 fun <T, S, U> rememberInfiniteQuery(
  key: InfiniteQueryKey<T, S>,

soil-query-compose/src/commonMain/kotlin/soil/query/compose/InfiniteQueryObject.kt

@@ -9,13 +9,38 @@ import soil.query.QueryFetchStatus
 import soil.query.QueryModel
 import soil.query.QueryStatus
 
+/**
+ * A InfiniteQueryObject represents [QueryModel]s interface for infinite fetching data using a retrieval method known as "infinite scroll."
+ *
+ * @param T Type of data to retrieve.
+ * @param S Type of parameter.
+ */
 @Stable
 sealed interface InfiniteQueryObject<out T, S> : QueryModel<T> {
+
+ /**
+ * Refreshes the data.
+ */
  val refresh: suspend () -> Unit
+
+ /**
+ * Fetches data for the [InfiniteQueryKey][soil.query.InfiniteQueryKey] using the [parameter][loadMoreParam].
+ */
  val loadMore: suspend (param: S) -> Unit
+
+ /**
+ * The parameter for next fetching. If null, it means there is no more data to fetch.
+ */
  val loadMoreParam: S?
 }
 
+/**
+ * A InfiniteQueryLoadingObject represents the initial loading state of the [InfiniteQueryObject].
+ *
+ * @param T Type of data to retrieve.
+ * @param S Type of parameter.
+ * @constructor Creates a [InfiniteQueryLoadingObject].
+ */
 @Immutable
 data class InfiniteQueryLoadingObject<T, S>(
  override val data: T?,
@@ -33,6 +58,13 @@ data class InfiniteQueryLoadingObject<T, S>(
  override val status: QueryStatus = QueryStatus.Pending
 }
 
+/**
+ * A InfiniteQueryLoadingErrorObject represents the initial loading error state of the [InfiniteQueryObject].
+ *
+ * @param T Type of data to retrieve.
+ * @param S Type of parameter.
+ * @constructor Creates a [InfiniteQueryLoadingErrorObject].
+ */
 @Immutable
 data class InfiniteQueryLoadingErrorObject<T, S>(
  override val data: T?,
@@ -50,6 +82,13 @@ data class InfiniteQueryLoadingErrorObject<T, S>(
  override val status: QueryStatus = QueryStatus.Failure
 }
 
+/**
+ * A InfiniteQuerySuccessObject represents the successful state of the [InfiniteQueryObject].
+ *
+ * @param T Type of data to retrieve.
+ * @param S Type of parameter.
+ * @constructor Creates a [InfiniteQuerySuccessObject].
+ */
 @Immutable
 data class InfiniteQuerySuccessObject<T, S>(
  override val data: T,
@@ -67,6 +106,15 @@ data class InfiniteQuerySuccessObject<T, S>(
  override val status: QueryStatus = QueryStatus.Success
 }
 
+/**
+ * A InfiniteQueryRefreshErrorObject represents the refresh error state of the [InfiniteQueryObject].
+ *
+ * This state is used when the data is successfully retrieved once, but an error occurs during the refresh or additional fetching.
+ *
+ * @param T Type of data to retrieve.
+ * @param S Type of parameter.
+ * @constructor Creates a [InfiniteQueryRefreshErrorObject].
+ */
 @Immutable
 data class InfiniteQueryRefreshErrorObject<T, S>(
  override val data: T,

soil-query-compose/src/commonMain/kotlin/soil/query/compose/MutationComposable.kt

@@ -14,6 +14,15 @@ import soil.query.MutationRef
 import soil.query.MutationState
 import soil.query.MutationStatus
 
+/**
+ * Remember a [MutationObject] and subscribes to the mutation state of [key].
+ *
+ * @param T Type of the return value from the mutation.
+ * @param S Type of the variable to be mutated.
+ * @param key The [MutationKey] for managing [mutation][soil.query.Mutation] associated with [id][soil.query.MutationId].
+ * @param client The [MutationClient] to resolve [key]. By default, it uses the [LocalSwrClient].
+ * @return A [MutationObject] each the mutation state changed.
+ */
 @Composable
 fun <T, S> rememberMutation(
  key: MutationKey<T, S>,
@@ -29,7 +38,6 @@ fun <T, S> rememberMutation(
  }
 }
 
-
 private fun <T, S> MutationState<T>.toObject(
  mutation: MutationRef<T, S>,
 ): MutationObject<T, S> {

soil-query-compose/src/commonMain/kotlin/soil/query/compose/MutationObject.kt

@@ -8,13 +8,37 @@ import androidx.compose.runtime.Stable
 import soil.query.MutationModel
 import soil.query.MutationStatus
 
+/**
+ * A MutationObject represents [MutationModel]s interface for mutating data.
+ *
+ * @param T Type of the return value from the mutation.
+ * @param S Type of the variable to be mutated.
+ */
 @Stable
 sealed interface MutationObject<out T, S> : MutationModel<T> {
+
+ /**
+ * Mutates the variable.
+ */
  val mutate: suspend (variable: S) -> T
+
+ /**
+ * Mutates the variable asynchronously.
+ */
  val mutateAsync: suspend (variable: S) -> Unit
+
+ /**
+ * Resets the mutation state.
+ */
  val reset: suspend () -> Unit
 }
 
+/**
+ * A MutationIdleObject represents the initial idle state of the [MutationObject].
+ *
+ * @param T Type of the return value from the mutation.
+ * @param S Type of the variable to be mutated.
+ */
 @Immutable
 data class MutationIdleObject<T, S>(
  override val data: T?,
@@ -29,6 +53,12 @@ data class MutationIdleObject<T, S>(
  override val status: MutationStatus = MutationStatus.Idle
 }
 
+/**
+ * A Mutation Loading Object represents the waiting execution result state of the [Mutation Object].
+ *
+ * @param T Type of the return value from the mutation.
+ * @param S Type of the variable to be mutated.
+ */
 @Immutable
 data class MutationLoadingObject<T, S>(
  override val data: T?,
@@ -43,6 +73,12 @@ data class MutationLoadingObject<T, S>(
  override val status: MutationStatus = MutationStatus.Pending
 }
 
+/**
+ * A MutationErrorObject represents the error state of the [MutationObject].
+ *
+ * @param T Type of the return value from the mutation.
+ * @param S Type of the variable to be mutated.
+ */
 @Immutable
 data class MutationErrorObject<T, S>(
  override val data: T?,
@@ -57,6 +93,12 @@ data class MutationErrorObject<T, S>(
  override val status: MutationStatus = MutationStatus.Failure
 }
 
+/**
+ * A MutationSuccessObject represents the successful state of the [MutationObject].
+ *
+ * @param T Type of the return value from the mutation.
+ * @param S Type of the variable to be mutated.
+ */
 @Immutable
 data class MutationSuccessObject<T, S>(
  override val data: T,

soil-query-compose/src/commonMain/kotlin/soil/query/compose/QueryComposable.kt

@@ -14,6 +14,14 @@ import soil.query.QueryRef
 import soil.query.QueryState
 import soil.query.QueryStatus
 
+/**
+ * Remember a [QueryObject] and subscribes to the query state of [key].
+ *
+ * @param T Type of data to retrieve.
+ * @param key The [QueryKey] for managing [query][soil.query.Query].
+ * @param client The [QueryClient] to resolve [key]. By default, it uses the [LocalSwrClient].
+ * @return A [QueryObject] each the query state changed.
+ */
 @Composable
 fun <T> rememberQuery(
  key: QueryKey<T>,
@@ -29,6 +37,16 @@ fun <T> rememberQuery(
  }
 }
 
+/**
+ * Remember a [QueryObject] and subscribes to the query state of [key].
+ *
+ * @param T Type of data to retrieve.
+ * @param U Type of selected data.
+ * @param key The [QueryKey] for managing [query][soil.query.Query].
+ * @param select A function to select data from [T].
+ * @param client The [QueryClient] to resolve [key]. By default, it uses the [LocalSwrClient].
+ * @return A [QueryObject] with selected data each the query state changed.
+ */
 @Composable
 fun <T, U> rememberQuery(
  key: QueryKey<T>,

soil-query-compose/src/commonMain/kotlin/soil/query/compose/QueryObject.kt

@@ -10,11 +10,25 @@ import soil.query.QueryModel
 import soil.query.QueryStatus
 
 
+/**
+ * A QueryObject represents [QueryModel]s interface for fetching data.
+ *
+ * @param T Type of data to retrieve.
+ */
 @Stable
 sealed interface QueryObject<out T> : QueryModel<T> {
+
+ /**
+ * Refreshes the data.
+ */
  val refresh: suspend () -> Unit
 }
 
+/**
+ * A QueryIdleObject represents the initial loading state of the [QueryObject].
+ *
+ * @param T Type of data to retrieve.
+ */
 @Immutable
 data class QueryLoadingObject<T>(
  override val data: T?,
@@ -30,6 +44,11 @@ data class QueryLoadingObject<T>(
  override val status: QueryStatus = QueryStatus.Pending
 }
 
+/**
+ * A QueryLoadingErrorObject represents the initial loading error state of the [QueryObject].
+ *
+ * @param T Type of data to retrieve.
+ */
 @Immutable
 data class QueryLoadingErrorObject<T>(
  override val data: T?,
@@ -45,6 +64,11 @@ data class QueryLoadingErrorObject<T>(
  override val status: QueryStatus = QueryStatus.Failure
 }
 
+/**
+ * A QuerySuccessObject represents the successful state of the [QueryObject].
+ *
+ * @param T Type of data to retrieve.
+ */
 @Immutable
 data class QuerySuccessObject<T>(
  override val data: T,
@@ -60,6 +84,14 @@ data class QuerySuccessObject<T>(
  override val status: QueryStatus = QueryStatus.Success
 }
 
+/**
+ * A QueryRefreshErrorObject represents the refresh error state of the [QueryObject].
+ *
+ * This state is used when the data is successfully retrieved once, but an error occurs during the refresh.
+ *
+ * @param T Type of data to retrieve.
+ * @constructor Creates a [QueryRefreshErrorObject].
+ */
 @Immutable
 data class QueryRefreshErrorObject<T>(
  override val data: T,

soil-query-compose/src/commonMain/kotlin/soil/query/compose/SwrClientProvider.kt

@@ -10,6 +10,12 @@ import androidx.compose.runtime.staticCompositionLocalOf
 import soil.query.SwrClient
 import soil.query.internal.uuid
 
+/**
+ * Provides a [SwrClient] to the [content] over [LocalSwrClient]
+ *
+ * @param client Applying to [LocalSwrClient].
+ * @param content The content under the [CompositionLocalProvider].
+ */
 @Composable
 fun SwrClientProvider(
  client: SwrClient,
@@ -27,6 +33,9 @@ fun SwrClientProvider(
  }
 }
 
+/**
+ * CompositionLocal for [SwrClient].
+ */
 val LocalSwrClient = staticCompositionLocalOf<SwrClient> {
  error("CompositionLocal 'SwrClient' not present")
 }