From bb869b526317667243141ae4368f0263f5cb8862 Mon Sep 17 00:00:00 2001
From: yanyongyu <yanyongyu_1@126.com>
Date: Mon, 9 Nov 2020 15:09:21 +0800
Subject: [PATCH] :memo: update matcher rule docs

---
 docs/guide/creating-a-matcher.md | 96 ++++++++++++++++++++------------
 1 file changed, 61 insertions(+), 35 deletions(-)

diff --git a/docs/guide/creating-a-matcher.md b/docs/guide/creating-a-matcher.md
index ea6771e3..6c0929e1 100644
--- a/docs/guide/creating-a-matcher.md
+++ b/docs/guide/creating-a-matcher.md
@@ -1,8 +1,8 @@
 # 注册事件响应器
 
-好了，现在插件已经创建完毕，我们可以开始编写实际代码了，本章将以一个简易单文件天气查询插件为例。
+好了，现在插件已经创建完毕，我们可以开始编写实际代码了，下面将以一个简易单文件天气查询插件为例。
 
-在 `weather.py` 中添加如下代码：
+在插件目录下 `weather.py` 中添加如下代码：
 
 ```python
 from nonebot import on_command
@@ -34,13 +34,13 @@ async def get_weather(city: str):
 
 为了简单起见，我们在这里的例子中没有接入真实的天气数据，但要接入也非常简单，你可以使用中国天气网、和风天气等网站提供的 API。
 
-下面我们来说明这段代码是如何工作的。
+接下来我们来说明这段代码是如何工作的。
 
 :::tip 提示
 从这里开始，你需要对 Python 的 asyncio 编程有所了解，因为 NoneBot 是完全基于 asyncio 的，具体可以参考 [廖雪峰的 Python 教程](https://www.liaoxuefeng.com/wiki/1016959663602400/1017959540289152)
 :::
 
-### 注册一个 [事件响应器](../api/matcher.md)
+## [事件响应器](../api/matcher.md)
 
 ```python{4}
 from nonebot import on_command
@@ -60,47 +60,30 @@ weather = on_command("天气", rule=to_me(), permission=Permission(), priority=5
 
 其他详细配置可以参考 API 文档，下面我们详细说明各个部分：
 
-#### 事件响应器类型 type
+### 事件响应器类型 type
 
-事件响应器类型其实就是对应 `Event.type` ，NoneBot 提供了一个基础类型事件响应器 `on()` 以及一些内置的事件响应器。
+事件响应器类型其实就是对应事件的类型 `Event.type` ，NoneBot 提供了一个基础类型事件响应器 `on()` 以及一些其他内置的事件响应器。
+
+以下所有类型的事件响应器都是由 `on(type, rule)` 的形式进行了简化封装。
 
 - `on("事件类型")`: 基础事件响应器，第一个参数为事件类型，空字符串表示不限
 - `on_metaevent()` ~ `on("meta_event")`: 元事件响应器
 - `on_message()` ~ `on("message")`: 消息事件响应器
 - `on_request()` ~ `on("request")`: 请求事件响应器
 - `on_notice()` ~ `on("notice")`: 通知事件响应器
-- `on_startswith(str)` ~ `on("message", startswith(str))`: 消息开头匹配处理器
-- `on_endswith(str)` ~ `on("message", endswith(str))`: 消息结尾匹配处理器
-- `on_command(str|tuple)` ~ `on("message", command(str|tuple))`: 命令处理器
-- `on_regex(pattern_str)` ~ `on("message", regex(pattern_str))`: 正则匹配处理器
+- `on_startswith(str)` ~ `on("message", startswith(str))`: 消息开头匹配响应器，参考 [startswith](../api/rule.md#startswith-msg)
+- `on_endswith(str)` ~ `on("message", endswith(str))`: 消息结尾匹配响应器，参考 [endswith](../api/rule.md#endswith-msg)
+- `on_keyword(set)` ~ `on("message", keyword(str))`: 消息关键词匹配响应器，参考 [keyword](../api/rule.md#keyword-keywords)
+- `on_command(str|tuple)` ~ `on("message", command(str|tuple))`: 命令响应器，参考 [command](../api/rule.md#command-cmds)
+- `on_regex(pattern_str)` ~ `on("message", regex(pattern_str))`: 正则匹配处理器，参考 [regex](../api/rule.md#regex-regex-flags-0)
 
-#### 匹配规则 rule
+### 匹配规则 rule
 
-事件响应器的匹配规则即 `Rule`，由非负个 `RuleChecker` 组成，当所有 `RuleChecker` 返回 `True` 时匹配成功。这些 `RuleChecker` 的形式如下：
+事件响应器的匹配规则即 `Rule`，详细内容在下方介绍。[直达](#自定义-rule)
 
-```python
-async def check(bot: Bot, event: Event, state: dict) -> bool:
-    return True
+### 优先级 priority
 
-def check(bot: Bot, event: Event, state: dict) -> bool:
-    return True
-```
-
-`Rule` 和 `RuleChecker` 之间可以使用 `与 &` 互相组合：
-
-```python
-from nonebot.rule import Rule
-
-Rule(async_checker1) & sync_checker & async_checker2
-```
-
-:::danger 警告
-`Rule(*checkers)` 只接受 async function，或使用 `nonebot.utils.run_sync` 自行包裹 sync function。在使用 `与 &` 时，NoneBot 会自动包裹 sync function
-:::
-
-#### 优先级 priority
-
-事件响应器的优先级代表事件响应器的执行顺序，同一优先级的事件响应器会 **同时执行！**
+事件响应器的优先级代表事件响应器的执行顺序，同一优先级的事件响应器会 **同时执行！**，优先级数字**越小**越先响应！优先级请从 `1` 开始排序！
 
 :::tip 提示
 使用 `nonebot-test` 可以看到当前所有事件响应器的执行流程，有助理解事件响应流程！
@@ -111,12 +94,55 @@ pip install nonebot2[test]
 
 :::
 
-#### 阻断 block
+### 阻断 block
 
 当有任意事件响应器发出了阻止事件传递信号时，该事件将不再会传递给下一优先级，直接结束处理。
 
 NoneBot 内置的事件响应器中，所有 `message` 类的事件响应器默认会阻断事件传递，其他则不会。
 
+## 自定义 rule
+
+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)
+- [regex(regex, flag)](../api/rule.md#regex-regex-flags-0)
+
+以上规则都是返回类型为 `Rule` 的函数，`Rule` 由非负个 `RuleChecker` 组成，当所有 `RuleChecker` 返回 `True` 时匹配成功。这些 `Rule`, `RuleChecker` 的形式如下：
+
+```python
+from nonebot.rule import Rule
+
+async def async_checker(bot: Bot, event: Event, state: dict) -> bool:
+    return True
+
+def sync_checker(bot: Bot, event: Event, state: dict) -> bool:
+    return True
+
+def check(arg1, args2):
+
+    async def _checker(bot: Bot, event: Event, state: dict) -> bool:
+        return bool(arg1 + arg2)
+    
+    return Rule(_check)
+```
+
+`Rule` 和 `RuleChecker` 之间可以使用 `与 &` 互相组合：
+
+```python
+from nonebot.rule import Rule
+
+Rule(async_checker1) & sync_checker & async_checker2
+```
+
+***请勿将事件处理的逻辑写入 `rule` 中，这会使得事件处理返回奇怪的响应。***
+
+:::danger 警告
+`Rule(*checkers)` 只接受 async function，或使用 `nonebot.utils.run_sync` 自行包裹 sync function。在使用 `与 &` 时，NoneBot 会自动包裹 sync function
+:::
+
 ### 编写事件处理函数 [Handler](../api/typing.md#handler)
 
 ```python{1,2,8,9}