修订文档

docs/converter.md

@@ -18,30 +18,27 @@ scopeNetLife {
 
 <img src="https://i.loli.net/2021/05/18/yUBmka6AjKsVleP.png" width="300"/>
 
+## 返回数据类型
 
-## 设置转换器
-转换器分为全局和单例, 单例可以覆盖全局的转换器. 如果不设置转换器就会采用默认的转换器
+Net支持请求返回的数据类型取决于你的转换器(也就是支持返回任何对象), 默认情况不创建转换器也支持返回以下数据类型
 
-=== "全局"
-    ```kotlin hl_lines="2"
-    NetConfig.init("http://github.com/") {
-        setConverter(SerializationConverter())
-    }
-    ```
-=== "单例"
-    ```kotlin hl_lines="3"
-    scopeNetLife {
-        tvFragment.text = Get<String>("api"){
-            converter = SerializationConverter()
-        }.await()
-    }
-    ```
+| 函数 | 描述 |
+|-|-|
+| String | 字符串 |
+| ByteArray | 字节数组 |
+| ByteString | 内部定义的一种字符串对象 |
+| Response | 最基础的响应 |
+| File | 文件对象, 这种情况其实应当称为[下载文件](download-file.md) |
 
-## 默认支持类型
+使用示例
 
-默认使用的是: [NetConverter.DEFAULT](https://github.com/liangjingkanji/Net/blob/master/net/src/main/java/com/drake/net/convert/NetConverter.kt)
+```kotlin
+scopeNetLife {
+    Get<Response>("api").await().headers("响应头名称") // 返回响应头
+}
+```
 
-??? summary "默认转换器源码"
+??? summary "默认使用的是: [NetConverter.DEFAULT](https://github.com/liangjingkanji/Net/blob/master/net/src/main/java/com/drake/net/convert/NetConverter.kt)"
     ```kotlin
     val DEFAULT = object : NetConverter {
 
@@ -64,17 +61,25 @@ scopeNetLife {
     }
     ```
 
-| 函数 | 描述 |
-|-|-|
-| String | 字符串 |
-| ByteArray | 字节数组 |
-| ByteString | 内部定义的一种字符串对象 |
-| Response | 最基础的响应 |
-| File | 文件对象, 这种情况其实应当称为`下载文件` |
-
+假设这里没有你需要的数据类型请[自定义转换器](#_3)(例如返回Json或Protocol)
 
-> 你的业务可能需要参数加密解密或者拼接参数, 请不要尝试封装Post或者Get等请求函数(这不是一个好主意), 自定义拦截器和转换器可以应对任何项目需求
+## 设置转换器
+转换器分为全局和单例, 单例可以覆盖全局的转换器. 如果不设置转换器就会采用默认的转换器
 
+=== "全局"
+    ```kotlin hl_lines="2"
+    NetConfig.init("http://github.com/") {
+        setConverter(SerializationConverter())
+    }
+    ```
+=== "单例"
+    ```kotlin hl_lines="3"
+    scopeNetLife {
+        tvFragment.text = Get<String>("api"){
+            converter = SerializationConverter()
+        }.await()
+    }
+    ```
 
 ## 自定义转换器
 

docs/error-handle.md

@@ -1,10 +1,29 @@
-Net具备完善的全局错误处理机制 <br>
+Net具备完善的错误处理机制
 
-默认情况下不需要去定义错误处理, 因为`NetErrorHandler`默认实现适用于大部分情况的错误处理.
+## 单例处理异常
+```kotlin
+scope {
+    val data = Get<String>("http://www.thisiserror.com/").await()
+}.catch {
+    // 协程内部发生错误回调, it为异常
+    handleError(it) // 该函数会将错误再次传递给全局错误回调处理
+}.finally {
+    // 协程内全部执行完成回调(包括子协程), it为异常
+}
+```
+
+以下函数幕后字段`it`为异常对象, 如果正常完成it则为null. 如果属于请求被手动取消则it为`CancellationException`
 
-但是如果你想要自定义或者监听错误, 你可以覆盖默认的错误处理.  在`initNet`或者`NetConfig.errorHandler`函数里面自定义全局错误处理
+| 函数 | 描述 |
+|-|-|
+| catch | 作用域被`catch`则不会被传递到全局异常处理回调中: [全局处理异常](error-handle.md), 除非使用`handleError`再次传递给全局 |
+| finally | 同样可以获取到异常对象, 且不影响全局异常回调处理 |
 
-## NetErrorHandler
+## 全局处理异常
+
+Net默认就会处理异常错误避免崩溃. 但是如果你想要自定义或者监听全局错误, 你可以覆盖默认的错误处理.  在`initNet`或者`NetConfig.errorHandler`函数里面自定义全局错误处理
+
+默认情况下不需要去定义错误处理, 因为`NetErrorHandler`默认实现适用于大部分情况的错误处理.
 
 |场景|处理函数|处理方式|
 |-|-|-|
@@ -35,22 +54,11 @@ NetConfig.init("http://localhost:80/") {
 > 本章末尾有默认实现的源码, 可供参考或者理解: [默认处理](#_2)
 
 
-## 手动错误处理
-
-假设不需要全局错误处理, 我们可以`catch`作用域来自己处理异常
-
-```kotlin
-scopeNetLife {
-    val data = Get<String>("http://www.thisiserror.com/").await()
-}.catch {
-    // 这里进行错误处理, it即为错误的异常对象
-}
-```
-
-catch里面的`it`属于异常对象, 这里列举可能存在的异常
+## 异常对象
 
-`scope/scopeLife`不会触发任何全局错误NetErrorHandler, 请使用单例错误处理方式`catch`, 因为`scope`用于处理异步任务,不应当用于网络请求
+以下为Net内部常见发生的异常对象. 不代表全部异常, 例如不包含开发者自己定义的异常
 
+> `scope/scopeLife`不会触发任何全局错误NetErrorHandler, 请使用单例错误处理方式`catch`, 因为`scope`用于处理异步任务,不应当用于网络请求
 
 
 | 异常 | 描述 |

docs/exception-track.md

@@ -1,4 +1,4 @@
-Net中网络请求导致的异常都会在LogCat中打印, 同时被全局的NetConfig的onError拦截到
+Net中网络请求导致的异常都会在LogCat中打印, 同时被全局的NetErrorHandler的onError拦截到
 
 > Net的异常对象通常会携带Request或者Response对象. 可以精准定位到请求信息
 

docs/kotlin-serialization.md

@@ -20,7 +20,7 @@
 
 ## 配置转换器
 
-这里使用Demo中的[SerializationConvert](https://github.com/liangjingkanji/Net/blob/master/sample/src/main/java/com/drake/net/sample/converter/SerializationConvert.kt)作演示.
+这里使用Demo中的[SerializationConvert](https://github.com/liangjingkanji/Net/blob/master/sample/src/main/java/com/drake/net/sample/converter/SerializationConverter.kt)作演示.
 如果你业务有特殊需要可以复制Demo中的转换器代码稍加修改
 
 === "全局配置"

docs/nested-scope.md

@@ -1,41 +0,0 @@
-有时候可能面临嵌套的`scope*`函数或者作用域内有子作用域情况, 这个时候的生命周期是如何
-
-
-## 嵌套Scope
-
-```kotlin hl_lines="5"
-scopeNet {
-    val task = Post<String>("api0").await()
-
-    scopeNet {
-        val task = Post<String>("api0").await() // 此时发生请求错误
-    }.catch {
-        // A
-    }
-}.catch {
-    // B
-}
-```
-
-- 以下嵌套作用域错误将会仅发生在`A`处, 并被捕获, 同时不影响外部`scopeNet`的请求和异常捕获
-- 两个`scopeNet`的异常抛出和捕获互不影响
-- `scopeNet/scopeDialog/scope`等函数同理
-
-## 子作用域
-
-```kotlin hl_lines="7 10"
-scopeNet {
-    val await = Post<String>("api").await()
-
-    launch {
-       val task = Post<String>("api0").await()  // 此时发生请求错误
-    }.invokeOnCompletion {
-        // A
-    }
-}.catch {
-     // B
-}
-```
-
-- 这种情况 先执行`A`然后执行`B`, 并且都能捕获异常.
-- 同时`scopeNet`发生错误也会导致`launch`内的请求被取消, `launch`发生错误也会导致`scopeNet`发生错误

docs/okhttp-client.md

@@ -1,4 +1,4 @@
-每个请求都会存在一个客户端对象(OkHttpClient)
+每个请求都会存在一个客户端对象, 既OkHttpClient
 
 Net在全局维护了一个OkHttpClient对象, 在NetConfig.okHttpClient的字段
 
@@ -8,7 +8,7 @@ object NetConfig {
 }
 ```
 
-同时每次可以创建一个新的客户端来发起请求区别于全局配置
+> 当然也支持创建一个新的客户端来发起请求(配置区别于全局客户端)
 
 ## 全局OkHttpClient
 

docs/scope.md

@@ -1,12 +1,14 @@
 Net的网络请求本身支持在官方的自带的作用域内使用, 但是考虑到完整的生命周期和错误处理等推荐使用Net内部定义的作用域.
 
-<br>
-全部使用顶层扩展函数
+> 全部使用顶层扩展函数
+
+本质上Net的请求动作函数返回的是一个Deferred对象. 可以在任何协程作用域内执行. 但是协程默认的作用域没有生命周期进行处理.
 
+这里建议你使用Net提供的创建作用域函数.
 
 ## 异步任务的作用域
 
-快速创建可以捕捉异常的协程作用域, 以下作用域不会触发全局错误处理
+创建可以捕捉异常的协程作用域, 但是不会触发`NetErrorHandler`(默认异常处理者)
 
 |函数|描述|
 |-|-|
@@ -31,31 +33,52 @@ Net的网络请求本身支持在官方的自带的作用域内使用, 但是考
 |`StateLayout.scope`|创建跟随[StateLayout](https://github.com/liangjingkanji/BRV)生命周期的作用域|
 
 <br>
-
 > PageRefreshLayout/StateLayout 属于[BRV](https://github.com/liangjingkanji/BRV)框架中的布局, 用于支持[自动化缺省页/下拉刷新](auto-state.md)
 <br>
 
-## 捕捉异常/执行完成
-```kotlin
-scope {
-    // scope系列函数的这个大括号里面就是作用域
+
+> 如果想了解详细的协程使用方式, 可以查看我的一篇文章: [最全面的Kotlin协程: Coroutine/Channel/Flow 以及实际应用](https://juejin.im/post/6844904037586829320)
+
+有时候可能面临嵌套的`scope*`函数或者作用域内有子作用域情况, 这个时候的生命周期是如何
+
+
+## 嵌套Scope
+
+```kotlin hl_lines="5"
+scopeNet {
+    val task = Post<String>("api0").await()
+
+    scopeNet {
+        val task = Post<String>("api0").await() // 此时发生请求错误
+    }.catch {
+        // A
+    }
 }.catch {
-    // 协程内部发生错误回调, it为异常
-    handleError(it) // 该函数会将错误再次传递给全局错误回调处理
-}.finally {
-    // 协程内全部执行完成回调(包括子协程), it为异常(如果正常完成则为null)
+    // B
 }
 ```
 
-以下函数幕后字段`it`为异常对象
+- 以下嵌套作用域错误将会仅发生在`A`处, 并被捕获, 同时不影响外部`scopeNet`的请求和异常捕获
+- 两个`scopeNet`的异常抛出和捕获互不影响
+- `scopeNet/scopeDialog/scope`等函数同理
 
-| 函数 | 描述 |
-|-|-|
-| catch | 作用域被`catch`则不会被传递到全局异常处理回调中: [全局处理异常](error-handle.md), 除非使用`handleError`再次传递给全局 |
-| finally | 同样可以获取到异常对象, 且不影响全局异常回调处理 |
+## 子作用域
 
+```kotlin hl_lines="7 10"
+scopeNet {
+    val await = Post<String>("api").await()
 
-> 如果想了解详细的协程使用方式, 可以查看我的一篇文章: [最全面的Kotlin协程: Coroutine/Channel/Flow 以及实际应用](https://juejin.im/post/6844904037586829320)
+    launch {
+       val task = Post<String>("api0").await()  // 此时发生请求错误
+    }.invokeOnCompletion {
+        // A
+    }
+}.catch {
+     // B
+}
+```
 
+- 这种情况 先执行`A`然后执行`B`, 并且都能捕获异常.
+- 同时`scopeNet`发生错误也会导致`launch`内的请求被取消, `launch`发生错误也会导致`scopeNet`发生错误
 
 

mkdocs.yml

@@ -41,33 +41,32 @@ nav:
   - 队列请求: enqueue-request.md
   - ViewModel: view-model.md
   - 请求对象: request.md
-  - 创建作用域: scope.md
   - 全局配置: config.md
-  - OkHttpClient: okhttp-client.md
-  - 全局错误处理: error-handle.md
-  - 拦截器: interceptor.md
-  - Https证书: https.md
-  - 自定义转换器:
+  - 转换数据:
       - 创建转换器: converter.md
       - 特殊结构解析: convert-special.md
       - kotlin-serialization: kotlin-serialization.md
       - 数据模型生成插件: model-generate.md
-  - 异常追踪: exception-track.md
   - 自动化:
       - 自动加载框: auto-dialog.md
       - 自动缺省页: auto-state.md
       - 自动下拉刷新: auto-refresh.md
       - 自动分页加载: auto-page.md
+  - 创建作用域: scope.md
   - 切换线程: switch-thread.md
+  - OkHttpClient: okhttp-client.md
+  - 错误处理: error-handle.md
+  - 定位异常: exception-track.md
+  - 拦截器: interceptor.md
   - 标签: tag.md
   - 上传文件: upload-file.md
   - 下载文件: download-file.md
   - 进度监听: progress.md
-  - 嵌套作用域: nested-scope.md
-  - 最快请求结果: fastest.md
+  - 取消请求: cancel.md
+  - Https证书: https.md
   - 重复请求: unique.md
   - 节流阀: debounce.md
-  - 取消请求: cancel.md
+  - 最快请求结果: fastest.md
   - 日志拦截器: log-recorder.md
   - 轮循器/倒计时: interval.md
   - 更新日志: updates.md