From 47b1affc56fb40ac5f0eb65c4a8b27730c10a564 Mon Sep 17 00:00:00 2001
From: yanyongyu <yanyongyu_1@126.com>
Date: Wed, 11 Nov 2020 16:49:11 +0800
Subject: [PATCH] :memo: update handler create doc

---
 docs/guide/creating-a-handler.md | 34 ++++++++++++++++++++++++++++++--
 docs/guide/creating-a-matcher.md |  8 ++++----
 docs/guide/installation.md       |  2 +-
 3 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/docs/guide/creating-a-handler.md b/docs/guide/creating-a-handler.md
index 1cbe6415..e1c4b77d 100644
--- a/docs/guide/creating-a-handler.md
+++ b/docs/guide/creating-a-handler.md
@@ -21,12 +21,42 @@ async def handle_city(bot: Bot, event: Event, state: dict):
     await weather.finish(city_weather)
 ```
 
-在之前的样例中，我们定义了两个函数，他们被事件响应器的装饰器装饰从而成为事件响应器的事件处理函数。
+在之前的样例中，我们定义了两个函数 `handle_first_receive`, `handle_city`，他们被事件响应器的装饰器装饰从而成为事件响应器的事件处理函数。
 
-### 装饰器
+:::tips 提示
+在事件响应器中，事件处理函数是**顺序**执行的！
+:::
+
+### 添加一个事件处理函数
 
 事件响应器提供了三种装饰事件处理函数的装饰器，分别是：
 
 1. [handle()](../api/matcher.md#classmethod-handle)
 2. [receive()](../api/matcher.md#classmethod-receive)
 3. [got(key, prompt, args_parser)](../api/matcher.md#classmethod-got-key-prompt-none-args-parser-none)
+
+#### handle()
+
+简单的为事件响应器添加一个事件处理函数，这个函数将会在上一个处理函数正常返回执行完毕后立即执行。
+
+#### receive()
+
+指示 NoneBot 接收一条新的用户消息后继续执行该处理函数。此时函数将会接收到新的消息而非前一条消息，之前相关信息可以存储在 state 中。
+
+特别的，当装饰的函数前没有其他事件处理函数，那么 `receive()` 不会接收一条新的消息而是直接使用第一条接收到的消息。
+
+#### got(key, prompt, args_parser)
+
+### 事件处理函数参数
+
+事件处理函数类型为 `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` 。
+
+参数分别为：
+
+1. [nonebot.typing.Bot](../api/typing.md#bot): 即事件上报连接对应的 Bot 对象，为 BaseBot 的子类。特别注意，此处的类型注释可以替换为指定的 Bot 类型，例如：`nonebot.adapters.cqhttp.Bot`，只有在上报事件的 Bot 类型与类型注释相符时才会执行该处理函数！可用于多平台进行不同的处理。
+2. [nonebot.typing.Event](../api/typing.md#event): 即上报事件对象，可以获取到上报的所有信息。
+3. `state`: 状态字典，可以存储任意的信息
+
+### 参数处理函数 args_parser
+
+### 逻辑控制
diff --git a/docs/guide/creating-a-matcher.md b/docs/guide/creating-a-matcher.md
index 6c0929e1..1a27246a 100644
--- a/docs/guide/creating-a-matcher.md
+++ b/docs/guide/creating-a-matcher.md
@@ -106,8 +106,8 @@ rule 的出现使得 nonebot 对事件的响应可以非常自由，nonebot 内
 
 - [startswith(msg)](../api/rule.md#startswith-msg)
 - [endswith(msg)](../api/rule.md#endswith-msg)
-- [keyword(*keywords)](../api/rule.md#keyword-keywords)
-- [command(*cmds)](../api/rule.md#command-cmds)
+- [keyword(\*keywords)](../api/rule.md#keyword-keywords)
+- [command(\*cmds)](../api/rule.md#command-cmds)
 - [regex(regex, flag)](../api/rule.md#regex-regex-flags-0)
 
 以上规则都是返回类型为 `Rule` 的函数，`Rule` 由非负个 `RuleChecker` 组成，当所有 `RuleChecker` 返回 `True` 时匹配成功。这些 `Rule`, `RuleChecker` 的形式如下：
@@ -125,7 +125,7 @@ def check(arg1, args2):
 
     async def _checker(bot: Bot, event: Event, state: dict) -> bool:
         return bool(arg1 + arg2)
-    
+
     return Rule(_check)
 ```
 
@@ -137,7 +137,7 @@ from nonebot.rule import Rule
 Rule(async_checker1) & sync_checker & async_checker2
 ```
 
-***请勿将事件处理的逻辑写入 `rule` 中，这会使得事件处理返回奇怪的响应。***
+**_请勿将事件处理的逻辑写入 `rule` 中，这会使得事件处理返回奇怪的响应。_**
 
 :::danger 警告
 `Rule(*checkers)` 只接受 async function，或使用 `nonebot.utils.run_sync` 自行包裹 sync function。在使用 `与 &` 时，NoneBot 会自动包裹 sync function
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
index 9d640dc2..907630c9 100644
--- a/docs/guide/installation.md
+++ b/docs/guide/installation.md
@@ -13,7 +13,7 @@ pip uninstall nonebot
 pip install nonebot2
 ```
 
-如果你需要使用最新的（可能尚未发布的）特性，可以直接从GitHub仓库安装：
+如果你需要使用最新的（可能尚未发布的）特性，可以直接从 GitHub 仓库安装：
 
 ```bash
 # master