💡: modify some comments

Author: junerver

hooks/src/commonMain/kotlin/xyz/junerver/compose/hooks/userequest/UseRequestOptions.kt

@@ -11,7 +11,7 @@ import xyz.junerver.compose.hooks.UseThrottleOptions
 import xyz.junerver.compose.hooks.userequest.utils.CachedData
 
 /*
-  Description: 请求参数
+  Description: Request options for useRequest hook
   Author: Junerver
   Date: 2024/1/31-9:58
   Email: junerver@gmail.com
@@ -25,109 +25,108 @@ internal typealias OnFinallyCallback<TParams, TData> = (TParams?, TData?, Throwa
 @Stable
 data class UseRequestOptions<TParams, TData> internal constructor(
     /**
-     * 默认 false。 即在初始化时自动执行 requestFn。
-     * 如果设置为 true，则需要手动调用 run
+     * Default false. Automatically execute requestFn on component mounted.
+     * If set to true, you need to manually call run
      */
     @Stable
     var manual: Boolean = false,
     /**
-     * 首次默认执行时，传递给 requestFn 的参数
+     * Parameters passed to requestFn when executed for the first time by default
      */
     var defaultParams: TParams? = null,
     /**
-     * requestFn 执行前触发
+     * Triggered before requestFn execution
      */
     @Stable
     var onBefore: OnBeforeCallback<TParams> = {},
     /**
-     * requestFn 成功时触发；参数1：请求返回值，参数2：请求参数
+     * Triggered when requestFn succeeds; param1: request return value, param2: request parameters
      */
     @Stable
     var onSuccess: OnSuccessCallback<TParams, TData> = { _, _ -> },
     /**
-     * requestFn 抛出异常时触发
+     * Triggered when requestFn throws an exception
      */
     @Stable
     var onError: OnErrorCallback<TParams> = { error, _ -> error.printStackTrace() },
     /**
-     * requestFn 执行完成时触发；参数1：请求参数，参数2：返回值，参数3：异常
+     * Triggered when requestFn execution completes; param1: request parameters, param2: return value, param3: exception
      */
     @Stable
     var onFinally: OnFinallyCallback<TParams, TData> = { _, _, _ -> },
     /**
-     * 错误重试次数。如果设置为 -1，则无限次重试。
+     * Number of error retries. If set to -1, retry infinitely.
      */
     @Stable
     var retryCount: Int = 0,
     /**
-     * 重试时间间隔，单位为毫秒。
-     * 如果不设置，默认采用简易的指数退避算法，取 1000 * 2 * retryCount
+     * Retry time interval in milliseconds.
+     * If not set, a simple exponential backoff algorithm is used by default, taking 1000 * 2 * retryCount
      */
     @Stable
     var retryInterval: Duration = Duration.ZERO,
     /**
-     * 轮询间隔，单位为毫秒。如果值大于 0，则处于轮询模式。
+     * Polling interval in milliseconds. If the value is greater than 0, it is in polling mode.
      */
     @Stable
     var pollingInterval: Duration = Duration.ZERO,
     /**
-     * 在页面隐藏时，是否继续轮询。如果设置为 false，在页面隐藏时会暂时停止轮询，页面重新显示时继续上次轮询。
+     * Whether to continue polling when the page is hidden. If set to false, polling will be temporarily stopped when the page is hidden, and will continue the last polling when the page is displayed again.
      */
     @Stable
     var pollingWhenHidden: Boolean = false,
     /**
-     * 轮询错误重试次数。如果设置为 -1，则无限次
+     * Number of polling error retries. If set to -1, retry infinitely
      */
     @Stable
     var pollingErrorRetryCount: Int = -1,
     /**
-     * 通过设置 options.ready，可以控制请求是否发出。当其值为 false 时，请求永远都不会发出。
+     * By setting options.ready, you can control whether the request is sent. When its value is false, the request will never be sent.
      *
-     * 其具体行为如下：
+     * Its specific behavior is as follows:
      *
-     * 当 [manual]=false 自动请求模式时，每次 [ready] 从 false 变为 true 时，都会自动发起请求，会带上参数 options.[defaultParams]。
-     * 当 [manual]=true 手动请求模式时，只要 [ready]=false，则通过 run/runAsync 触发的请求都不会执行。
+     * When [manual]=false (automatic request mode), every time [ready] changes from false to true, a request will be automatically initiated with the parameter options.[defaultParams].
+     * When [manual]=true (manual request mode), as long as [ready]=false, requests triggered by run/runAsync will not be executed.
      */
     var ready: Boolean = true,
     /**
-     * 通过设置 options.[refreshDeps]，在依赖变化时， [useRequest] 会自动调用 [Fetch.refresh] 方法，实现刷新（重复上一次请求）的效果。
-     * 如果设置 options.[manual] = true，则 [refreshDeps] 不再生效
+     * By setting options.[refreshDeps], when dependencies change, [useRequest] will automatically call the [Fetch.refresh] method to achieve the effect of refreshing (repeating the last request).
+     * If options.[manual] = true is set, [refreshDeps] will no longer take effect
      */
     var refreshDeps: Array<Any?> = emptyArray(),
     /**
-     * 如果存在依赖刷新Action函数，则不执行默认的[Fetch.refresh]函数，改为执行[refreshDepsAction]
+     * If there is a dependency refresh Action function, the default [Fetch.refresh] function will not be executed, and [refreshDepsAction] will be executed instead
      */
     var refreshDepsAction: (() -> Unit)? = null,
     /**
-     * 请求的唯一标识。相同 cacheKey 的数据全局同步（cacheTime、staleTime 参数会使该机制失效
+     * Unique identifier for the request. Data with the same cacheKey is globally synchronized (cacheTime and staleTime parameters will disable this mechanism)
      */
     @Stable
     var cacheKey: String = "",
     /**
-     * 设置缓存数据回收时间。默认缓存数据 5 分钟后回收
-     * 如果设置为 `(-1).seconds`, 则表示缓存数据永不过期
+     * Set cache data recycle time. By default, cache data is recycled after 5 minutes
+     * If set to `(-1).seconds`, it means cache data never expires
      */
     @Stable
     var cacheTime: Duration = 5.minutes,
     /**
-     * 缓存数据保持新鲜时间。在该时间间隔内，认为数据是新鲜的，不会重新发请求
-     * 如果设置为 `(-1).seconds`，则表示数据永远新鲜
+     * Cache data freshness time. Within this time interval, the data is considered fresh and no new request will be made
+     * If set to `(-1).seconds`, it means the data is always fresh
      */
     @Stable
     var staleTime: Duration = Duration.ZERO,
     /**
-     * 自定义缓存策略，无则采取默认策略
+     * Custom cache strategy, if none, use default strategy
      */
     @Stable
     var setCache: ((data: CachedData<TData>) -> Unit)? = null,
     @Stable
     var getCache: ((params: TParams) -> CachedData<TData>)? = null,
     /**
-     * 通过设置 options.[loadingDelay] ，可以延迟 [FetchState.loading] 变成 true 的时间，有效防止闪烁。
-     * 例如当一个接口正常会较快返回，我们如果常规使用会出现闪烁。从请求发起后，极快的从 false -> true ->false;
-     * 我们可以设置一个大于这个返回时长的[loadingDelay]，例如[50.milliseconds]，这样在50ms内返回的接口，
-     * 不会引起闪烁。这种闪烁其实还有一种变形场景，例如一个接口会极快返回，我们不希望用户继续快速点击，我们期望
-     * 将loading延时，增加loading的对外表现时间，这种需求接近于节流，又稍有区别
+     * By setting options.[loadingDelay], you can delay the time when [FetchState.loading] becomes true, effectively preventing flickering.
+     * For example, when an interface normally returns quickly, if we use it conventionally, flickering will occur. After the request is initiated, it changes very quickly from false -> true -> false;
+     * We can set a [loadingDelay] that is greater than this return duration, such as [50.milliseconds], so that interfaces that return within 50ms will not cause flickering.
+     * This flickering actually has another variant scenario, for example, an interface will return very quickly, we don't want users to continue clicking quickly, we expect to delay loading and increase the external performance time of loading, this requirement is close to throttling, but slightly different
      */
     @Stable
     var loadingDelay: Duration = Duration.ZERO,
@@ -141,13 +140,13 @@ data class UseRequestOptions<TParams, TData> internal constructor(
     }
 
     /**
-     * 通过配置参数为 [UseDebounceOptions.wait] 开启防抖功能，默认值为0，不开启防抖
+     * Enable debounce functionality by configuring [UseDebounceOptions.wait], default value is 0, debounce is not enabled
      */
     @Stable
     internal var debounceOptions: UseDebounceOptions = UseDebounceOptions.optionOf { wait = Duration.ZERO }
 
     /**
-     * 通过配置参数为 [UseThrottleOptions.wait] 开启节流功能，默认值为0，不开启节流
+     * Enable throttle functionality by configuring [UseThrottleOptions.wait], default value is 0, throttle is not enabled
      */
     @Stable
     internal var throttleOptions: UseThrottleOptions = UseThrottleOptions.optionOf { wait = Duration.ZERO }
@@ -220,7 +219,7 @@ data class UseRequestOptions<TParams, TData> internal constructor(
 }
 
 /**
- * 使用代理来实现通过函数配置防抖选项
+ * Use delegate to implement debounce options configuration through functions
  */
 private class DebounceOptionsDelegate(
     private var configure: UseDebounceOptions.() -> Unit,
@@ -238,7 +237,7 @@ private class DebounceOptionsDelegate(
 }
 
 /**
- * 使用代理来实现通过函数配置节流选项
+ * Use delegate to implement throttle options configuration through functions
  */
 private class ThrottleOptionsDelegate(
     private var configure: UseThrottleOptions.() -> Unit,

hooks/src/commonMain/kotlin/xyz/junerver/compose/hooks/userequest/useRequest.kt

@@ -38,63 +38,81 @@ typealias ComposablePluginGenFn<TParams, TData> = @Composable (UseRequestOptions
 */
 
 /**
- * Description: 一个用来管理网络状态的Hook，它可以非常方便的接入到传统的 retrofit 网络请求模式中。
- * 你几乎不需要做任何额外工作，就可以简单高效的在 Compose 中使用网络请求，并将请求数据作为状态，直接驱动UI。
+ * A hook for managing network request state that can be easily integrated with traditional Retrofit network request patterns.
+ * You need almost no additional work to use network requests simply and efficiently in Compose,
+ * and use request data as state to directly drive the UI.
  *
- * [SuspendNormalFunction]
- * 是所有函数的抽象，我们最终通过函数拿到的手动执行函数也是[SuspendNormalFunction]类型的，
- * 调用时要传递的是[arrayOf]的参数。
+ * [SuspendNormalFunction] is an abstraction of all functions. The manual execution function we finally get through the function
+ * is also of type [SuspendNormalFunction], and the parameters passed when calling are [arrayOf].
  *
- * 我还额外提供了两个方便的转换函数
- * [asNoopFn]、[asSuspendNoopFn]，这两个函数可以把任意的Kotlin函数转换成[useRequest]需要的函数。
- * 需要注意区分，如果是挂起函数就需要调用[asSuspendNoopFn]，否则就使用
- * [asNoopFn]，通过这个函数我们可以简化普通函数到[SuspendNormalFunction]的包装过程。
+ * Two convenient conversion functions [asNoopFn] and [asSuspendNoopFn] are also provided,
+ * which can convert any Kotlin function to the function required by [useRequest].
+ * Note the distinction: if it is a suspend function, you need to call [asSuspendNoopFn], otherwise use [asNoopFn].
+ * Through this function, we can simplify the wrapping process from ordinary functions to [SuspendNormalFunction].
  *
- * 示例代码：
+ * Example usage:
  *
  * ```kotlin
- * @Parcelize
- * data class Resp<T : Parcelable?>(
- *     val message: String,
- *     val status: Int,
- *     val data: T?
- * ) : Parcelable
+ * // Auto request with default parameters
+ * val (userInfo, loading, error) = useRequest(
+ *     requestFn = { NetApi.userInfo(it) },
+ *     optionsOf = {
+ *         defaultParams = "junerver" // Auto requests must set default parameters
+ *     }
+ * )
  *
- * @Parcelize
- * data class LoginSucc(
- *     val expire: String,
- *     val token: String
- * ) : Parcelable
+ * // Manual request
+ * val (repoInfo, loading, error, request) = useRequest(
+ *     requestFn = { params: Tuple2<String, String> ->
+ *         NetApi.repoInfo(params.first, params.second)
+ *     },
+ *     optionsOf = {
+ *         manual = true
+ *         defaultParams = tuple("junerver", "ComposeHooks")
+ *     }
+ * )
  *
- * interface WebService {
- *     //登录
- *     @Headers("Content-Type:application/json;charset=UTF-8")
- *     @POST("api/cas/login/restful")
- *     suspend fun login(@Body body: RequestBody): Resp<LoginSucc>
- * }
- *
- * // 自定义一个传递Retrofit接口实例的扩展函数，省去调用 `asSuspendNoopFn` 每次都要传递实例的步骤
- * fun <T : Any> KFunction<T?>.asRequestFn()
- *      = this.asSuspendNoopFn(NetFetchManager.INSTANCE)
- *
- * // 现在你可以放心的使用状态了，通过解构赋值拿到的 data 可以直接应用在 Compose UI 中
- * val (data, loading, err, run) = useRequest(
- *      WebService::login.asRequestFn(),
- *      optionsOf {defaultParams = arrayOf(bodyreq)}
- *   )
+ * // Using asSuspendNoopFn for direct function reference
+ * val (userInfo, loading, error) = useRequest(
+ *     requestFn = NetApi::userInfo.asSuspendNoopFn(),
+ *     optionsOf = {
+ *         defaultParams = tuple("junerver")
+ *     }
+ * )
  * ```
  *
- * 是的，它可以简单到只有一行代码，通过[UseRequestOptions]选项配置，你可以设置：手动请求、Ready、错误重试、
- * 生命周期回调、轮询、防抖、节流、依赖刷新等待功能。
+ * Through [UseRequestOptions] configuration, you can set: manual request, ready state, error retry,
+ * lifecycle callbacks, polling, debounce, throttle, dependency refresh and other functions.
  *
- * Tips: 强烈建议开启Android Studio中类型镶嵌提示，位于：Editor - Inlay Hints - Types -
- * Kotlin，它可以 更高效的提示我们解构赋值后拿到的相关状态、函数的类型。
+ * Tips: It is strongly recommended to enable type inlay hints in Android Studio, located at:
+ * Editor - Inlay Hints - Types - Kotlin, which can more efficiently prompt us about the types of
+ * related states and functions obtained after destructuring assignment.
+ *
+ * @param requestFn The abstracted request function: suspend (TParams) -> TData.
+ *   If you don't like using [asSuspendNoopFn], you can also use anonymous [suspend] closures.
+ * @param optionsOf Configuration factory function for request options, see [UseRequestOptions]
+ * @param plugins Custom plugins array, pass through arrayOf
+ * @return [RequestHolder] containing data state, loading state, error state, and control functions
+ */
+@Composable
+fun <TParams, TData : Any> useRequest(
+    requestFn: SuspendNormalFunction<TParams, TData>,
+    optionsOf: UseRequestOptions<TParams, TData>.() -> Unit = {},
+    plugins: Array<ComposablePluginGenFn<TParams, TData>> = emptyArray(),
+): RequestHolder<TParams, TData> = useRequestPrivate(
+    requestFn,
+    useDynamicOptions(optionsOf),
+    plugins,
+)
+
+/**
+ * Internal implementation of useRequest hook with full plugin support.
+ * This function handles the core logic of request management including plugin initialization,
+ * state management, and request execution.
  *
- * @param requestFn 经过抽象后的请求函数：suspend (TParams) ->
- *    TData，如果你不喜欢使用[asSuspendNoopFn]，也可以使用匿名 [suspend]闭包。
- * @param options
- *    请求的配置项，参考[RequestOptions]，以及[ahooks-useRequest](https://ahooks.gitee.io/zh-CN/hooks/use-request/index).
- * @param plugins 自定义的插件，这是一个数组，请通过arrayOf传入
+ * @param requestFn The abstracted request function: suspend (TParams) -> TData
+ * @param options Request configuration options, see [UseRequestOptions]
+ * @param plugins Custom plugins array, pass through arrayOf
  */
 @Composable
 private fun <TParams, TData : Any> useRequestPrivate(
@@ -146,20 +164,15 @@ private fun <TParams, TData : Any> useRequestPrivate(
 }
 
 /**
- * 性能优化版本，[optionsOf] 是一个普通的内联函数，他会在每次组件重组时调用，这回带来一些性能上的损耗，我们可以简单呢的通过 [remember]，进行优化。
- * 在未来版本将会把原始的直接传递对象这类api转变为私有，只允许通过闭包方式使用。
+ * Internal implementation function that creates and configures the Fetch instance with plugins.
+ * This function handles the low-level details of state management, plugin initialization,
+ * and coroutine scope management for the request lifecycle.
+ *
+ * @param requestFn The request function to be executed
+ * @param options Configuration options for the request behavior
+ * @param plugins Array of plugins to be applied to the request
+ * @return Configured Fetch instance ready for use
  */
-@Composable
-fun <TParams, TData : Any> useRequest(
-    requestFn: SuspendNormalFunction<TParams, TData>,
-    optionsOf: UseRequestOptions<TParams, TData>.() -> Unit = {},
-    plugins: Array<ComposablePluginGenFn<TParams, TData>> = emptyArray(),
-): RequestHolder<TParams, TData> = useRequestPrivate(
-    requestFn,
-    useDynamicOptions(optionsOf),
-    plugins,
-)
-
 @Composable
 private fun <TParams, TData : Any> useRequestPluginsImpl(
     requestFn: SuspendNormalFunction<TParams, TData>,
@@ -196,6 +209,21 @@ private fun <TParams, TData : Any> useRequestPluginsImpl(
     return fetch
 }
 
+/**
+ * Holder class that encapsulates all the state and control functions returned by useRequest hook.
+ * This class provides a structured way to access request data, loading state, error state,
+ * and various control functions for managing the request lifecycle.
+ *
+ * @param TParams The type of parameters passed to the request function
+ * @param TData The type of data returned by the request function
+ * @property data State containing the response data, null if no data has been loaded yet
+ * @property isLoading State indicating whether a request is currently in progress
+ * @property error State containing any error that occurred during the request, null if no error
+ * @property request Function to manually trigger a request with optional parameters
+ * @property mutate Function to manually update the data state without making a request
+ * @property refresh Function to refresh the request using the last used parameters
+ * @property cancel Function to cancel any ongoing request
+ */
 @Stable
 data class RequestHolder<TParams, TData>(
     val data: State<TData?>,