更新函数注释

net/src/main/java/com/drake/net/NetConfig.kt

@@ -28,7 +28,6 @@ import com.drake.net.NetConfig.dialogFactory
 import com.drake.net.NetConfig.errorHandler
 import com.drake.net.NetConfig.host
 import com.drake.net.NetConfig.logEnabled
-import com.drake.net.NetConfig.onError
 import com.drake.net.NetConfig.requestInterceptor
 import com.drake.net.NetConfig.runningCalls
 import com.drake.net.convert.NetConverter
@@ -42,7 +41,7 @@ import okhttp3.Call
 import okhttp3.OkHttpClient
 import java.lang.ref.WeakReference
 import java.net.UnknownHostException
-import java.util.concurrent.*
+import java.util.concurrent.ConcurrentLinkedQueue
 
 
 /**
@@ -61,19 +60,36 @@ import java.util.concurrent.*
 object NetConfig {
 
     lateinit var app: Application
+
+    /** 全局域名 */
+    var host: String = ""
+
+    /** 全局单例请求客户端 */
     var okHttpClient: OkHttpClient = OkHttpClient.Builder().toNetOkhttp().build()
         set(value) {
             field = value.toNetOkhttp()
         }
-    var host: String = ""
+
+    /** 是否启用日志 */
     var logEnabled = true
+
+    /** 运行中的请求 */
     var runningCalls: ConcurrentLinkedQueue<WeakReference<Call>> = ConcurrentLinkedQueue()
         private set
+
+    /** 请求拦截器 */
     var requestInterceptor: RequestInterceptor? = null
+
+    /** 响应数据转换器 */
     var converter: NetConverter = NetConverter
+
+    /** 错误处理器 */
     var errorHandler: NetErrorHandler = NetErrorHandler
+
+    /** 对话框构建工厂 */
     var dialogFactory: NetDialogFactory = NetDialogFactory
 
+    /** 对话框, 已废弃, 请使用[dialogFactory] */
     @Deprecated("废弃", replaceWith = ReplaceWith("NetConfig.dialogFactory"))
     var onDialog: (FragmentActivity) -> Dialog = { activity ->
         val progress = ProgressDialog(activity)
@@ -81,6 +97,7 @@ object NetConfig {
         progress
     }
 
+    /** 全局错误处理器, 已废弃, 请使用[errorHandler] */
     @Deprecated("使用NetErrorHandler统一处理错误", replaceWith = ReplaceWith("NetConfig.errorHandler"))
     var onError: Throwable.() -> Unit = onError@{
 
@@ -108,6 +125,7 @@ object NetConfig {
     }
 
 
+    /** 网络请求自动处理缺省页时发生错误的处理逻辑 */
     @Deprecated("使用NetErrorHandler统一处理错误", replaceWith = ReplaceWith("NetConfig.errorHandler"))
     var onStateError: Throwable.(view: View) -> Unit = {
         when (this) {
@@ -133,6 +151,12 @@ object NetConfig {
         okHttpClient = builder.toNetOkhttp().build()
     }
 
+    /**
+     * 初始化框架, 该函数仅在Kotlin下有效
+     *
+     * @param host 请求url的主机名
+     * @param config 进行配置网络请求
+     */
     fun init(host: String = "", config: OkHttpClient.Builder) {
         NetConfig.host = host
         okHttpClient = config.toNetOkhttp().build()

net/src/main/java/com/drake/net/callback/DialogCallback.kt

@@ -3,6 +3,7 @@
 package com.drake.net.callback
 
 import android.app.Dialog
+import androidx.annotation.MainThread
 import androidx.fragment.app.FragmentActivity
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleObserver
@@ -27,6 +28,8 @@ abstract class DialogCallback<T> constructor(
     val cancelable: Boolean = true,
 ) : NetCallback<T>(), LifecycleObserver {
 
+    /** 网络请求开始 */
+    @MainThread
     override fun onStart(request: Request) {
         super.onStart(request)
         activity.lifecycle.addObserver(this)
@@ -48,6 +51,11 @@ abstract class DialogCallback<T> constructor(
         }
     }
 
+    /**
+     * 网络请求完成
+     * @param e 假设请求过程中发生错误则不为null
+     */
+    @MainThread
     override fun onComplete(call: Call, e: Throwable?) {
         dismiss()
         super.onComplete(call, e)

net/src/main/java/com/drake/net/callback/PageCallback.kt

@@ -1,6 +1,7 @@
 package com.drake.net.callback
 
 import android.view.View
+import androidx.annotation.MainThread
 import com.drake.brv.PageRefreshLayout
 import com.drake.net.Net
 import com.drake.net.NetConfig
@@ -17,6 +18,9 @@ import java.util.concurrent.CancellationException
  * 会在页面被销毁时自动取消网络请求
  */
 abstract class PageCallback<T>(val page: PageRefreshLayout) : NetCallback<T>() {
+
+    /** 网络请求开始 */
+    @MainThread
     override fun onStart(request: Request) {
         super.onStart(request)
         page.addOnAttachStateChangeListener(object : View.OnAttachStateChangeListener {
@@ -30,11 +34,20 @@ abstract class PageCallback<T>(val page: PageRefreshLayout) : NetCallback<T>() {
         })
     }
 
+    /**
+     * 网络请求失败, 异步线程
+     * @param e 请求过程中发生错误则
+     */
     override fun onFailure(call: Call, e: IOException) {
         page.showError(e)
         super.onFailure(call, e)
     }
 
+    /**
+     * 网络请求完成
+     * @param e 请求过程中发生错误则
+     */
+    @MainThread
     override fun onError(call: Call, e: IOException) {
         if (page.loaded || !page.stateEnabled) {
             NetConfig.errorHandler.onError(e)
@@ -43,6 +56,11 @@ abstract class PageCallback<T>(val page: PageRefreshLayout) : NetCallback<T>() {
         }
     }
 
+    /**
+     * 网络请求完成
+     * @param e 假设请求过程中发生错误则不为null
+     */
+    @MainThread
     override fun onComplete(call: Call, e: Throwable?) {
         if (e == null || e is CancellationException) {
             page.showContent()

net/src/main/java/com/drake/net/callback/StateCallback.kt

@@ -1,6 +1,7 @@
 package com.drake.net.callback
 
 import android.view.View
+import androidx.annotation.MainThread
 import com.drake.net.Net
 import com.drake.net.NetConfig
 import com.drake.net.interfaces.NetCallback
@@ -18,6 +19,8 @@ import java.util.concurrent.CancellationException
  */
 abstract class StateCallback<T>(val state: StateLayout) : NetCallback<T>() {
 
+    /** 网络请求开始 */
+    @MainThread
     override fun onStart(request: Request) {
         super.onStart(request)
         state.addOnAttachStateChangeListener(object : View.OnAttachStateChangeListener {
@@ -30,15 +33,29 @@ abstract class StateCallback<T>(val state: StateLayout) : NetCallback<T>() {
         })
     }
 
+    /**
+     * 网络请求失败, 异步线程
+     * @param e 请求过程中发生错误则
+     */
     override fun onFailure(call: Call, e: IOException) {
         state.showError(e)
         super.onFailure(call, e)
     }
 
+    /**
+     * 网络请求完成
+     * @param e 请求过程中发生错误则
+     */
+    @MainThread
     override fun onError(call: Call, e: IOException) {
         NetConfig.errorHandler.onStateError(e, state)
     }
 
+    /**
+     * 网络请求完成
+     * @param e 假设请求过程中发生错误则不为null
+     */
+    @MainThread
     override fun onComplete(call: Call, e: Throwable?) {
         super.onComplete(call, e)
         if (e == null || e is CancellationException) state.showContent()

net/src/main/java/com/drake/net/convert/NetConverter.kt

@@ -32,6 +32,8 @@ interface NetConverter {
     companion object DEFAULT : NetConverter {
         /**
          * 返回结果应当等于泛型对象, 可空
+         * @param succeed 请求要求返回的泛型类型
+         * @param response 请求响应对象
          */
         override fun <R> onConvert(succeed: Type, response: Response): R? {
             return when {
@@ -40,10 +42,7 @@ interface NetConverter {
                 succeed.toString().contentEquals("byte[]") -> response.body?.bytes() as R
                 succeed === Response::class.java -> response as R
                 succeed === File::class.java -> response.file() as R
-                else -> throw ConvertException(
-                    response,
-                    "An exception occurred while converting the NetConverter.DEFAULT"
-                )
+                else -> throw ConvertException(response, "An exception occurred while converting the NetConverter.DEFAULT")
             }
         }
     }

net/src/main/java/com/drake/net/interfaces/NetCallback.kt

@@ -47,6 +47,10 @@ abstract class NetCallback<T> constructor(
         }
     }
 
+    /**
+     * 网络请求错误, 异步线程
+     * @param e 请求过程中发生错误则
+     */
     override fun onFailure(call: Call, e: IOException) {
         val message = e.cause?.message
         if (message == "Socket closed") {

net/src/main/java/com/drake/net/interfaces/NetDialogFactory.kt

@@ -5,6 +5,11 @@ import androidx.fragment.app.FragmentActivity
 import com.drake.net.NetConfig
 
 fun interface NetDialogFactory {
+
+    /**
+     * 构建并返回一个Dialog
+     * @param activity 请求发生所在的[FragmentActivity]
+     */
     fun onCreate(activity: FragmentActivity): Dialog
 
     companion object DEFAULT : NetDialogFactory {

net/src/main/java/com/drake/net/interfaces/NetErrorHandler.kt

@@ -5,15 +5,18 @@ import com.drake.net.NetConfig
 
 interface NetErrorHandler {
 
+    companion object DEFAULT : NetErrorHandler
+
     /**
      * 全局错误
+     * @param e 发生的错误
      */
     fun onError(e: Throwable) = NetConfig.onError(e)
 
     /**
      * 自动缺省页错误
+     * @param e 发生的错误
+     * @param view 缺省页, StateLayout或者PageRefreshLayout
      */
     fun onStateError(e: Throwable, view: View) = NetConfig.onStateError(e, view)
-
-    companion object DEFAULT : NetErrorHandler
 }

net/src/main/java/com/drake/net/interfaces/ProgressListener.kt

@@ -31,6 +31,7 @@ abstract class ProgressListener(var interval: Long = 500) {
 
     /**
      * 监听上传/下载进度回调函数
+     * @param p 上传或者下载进度
      */
     abstract fun onProgress(p: Progress)
 }

net/src/main/java/com/drake/net/time/Interval.kt

@@ -33,7 +33,7 @@ import java.io.Serializable
 import java.util.concurrent.TimeUnit
 
 /**
- * 轮循器
+ * 创建一个会自动结束的轮循器
  *
  * 操作
  * 1. 开启 [start] 只有在闲置状态下才可以开始
@@ -62,6 +62,13 @@ open class Interval(
     private val initialDelay: Long = 0
 ) : Serializable, Closeable {
 
+    /**
+     * 创建一个不会自动结束的轮询器/计时器
+     *
+     * @param period 间隔时间
+     * @param unit 时间单位
+     * @param initialDelay 初次间隔时间, 默认为0即立即开始
+     */
     constructor(
         period: Long,
         unit: TimeUnit,
@@ -139,6 +146,9 @@ open class Interval(
         state = IntervalStatus.STATE_IDLE
     }
 
+    /** 等于[cancel] */
+    override fun close() = cancel()
+
     /**
      * 切换轮循器开始或结束
      * 假设轮询器为暂停[IntervalStatus.STATE_PAUSE]状态将继续运行[resume]
@@ -151,16 +161,6 @@ open class Interval(
         }
     }
 
-    /**
-     * 继续
-     * 要求轮循器为暂停状态[IntervalStatus.STATE_PAUSE], 否则无效
-     */
-    fun resume() {
-        if (state != IntervalStatus.STATE_PAUSE) return
-        state = IntervalStatus.STATE_ACTIVE
-        launch(delay)
-    }
-
     /**
      * 暂停
      */
@@ -171,6 +171,16 @@ open class Interval(
         delay = System.currentTimeMillis() - countTime
     }
 
+    /**
+     * 继续
+     * 要求轮循器为暂停状态[IntervalStatus.STATE_PAUSE], 否则无效
+     */
+    fun resume() {
+        if (state != IntervalStatus.STATE_PAUSE) return
+        state = IntervalStatus.STATE_ACTIVE
+        launch(delay)
+    }
+
     /**
      * 重置
      */
@@ -227,9 +237,5 @@ open class Interval(
             }
         }
     }
-
-    override fun close() {
-        cancel()
-    }
 }