💡 add docstrings

nonebot/typing.py

@@ -1,12 +1,12 @@
-"""
-## 类型
+"""本模块定义了 NoneBot 模块中共享的一些类型。
 
-下面的文档中，「类型」部分使用 Python 的 Type Hint 语法，见 [`PEP 484`](https://www.python.org/dev/peps/pep-0484/)、[`PEP 526`](https://www.python.org/dev/peps/pep-0526/) 和 [`typing`](https://docs.python.org/3/library/typing.html)。
+下面的文档中，「类型」部分使用 Python 的 Type Hint 语法，
+参考 [`PEP 484`](https://www.python.org/dev/peps/pep-0484/),
+[`PEP 526`](https://www.python.org/dev/peps/pep-0526/) 和
+[`typing`](https://docs.python.org/3/library/typing.html)。
 
 除了 Python 内置的类型，下面还出现了如下 NoneBot 自定类型，实际上它们是 Python 内置类型的别名。
 
-以下类型均可从 nonebot.typing 模块导入。
-
 FrontMatter:
     sidebar_position: 11
     description: nonebot.typing 模块
@@ -25,13 +25,15 @@ from typing import (
 if TYPE_CHECKING:
     from asyncio import Task
 
-    from nonebot.adapters import Bot, Event
+    from nonebot.adapters import Bot
     from nonebot.permission import Permission
 
 T_Wrapped = TypeVar("T_Wrapped", bound=Callable)
 
 
-def overrides(InterfaceClass: object):
+def overrides(InterfaceClass: object) -> Callable[[T_Wrapped], T_Wrapped]:
+    """标记一个方法为父类 interface 的 implement"""
+
     def overrider(func: T_Wrapped) -> T_Wrapped:
         assert func.__name__ in dir(InterfaceClass), f"Error method: {func.__name__}"
         return func
@@ -40,32 +42,21 @@ def overrides(InterfaceClass: object):
 
 
 T_State = Dict[Any, Any]
-"""
-事件处理状态 State 类型
-"""
+"""事件处理状态 State 类型"""
 
 T_BotConnectionHook = Callable[["Bot"], Awaitable[None]]
-"""
-Bot 连接建立时执行的函数
-"""
+"""Bot 连接建立时插槽函数"""
 T_BotDisconnectionHook = Callable[["Bot"], Awaitable[None]]
-"""
-Bot 连接断开时执行的函数
-"""
+"""Bot 连接断开时插槽函数"""
 T_CallingAPIHook = Callable[["Bot", str, Dict[str, Any]], Awaitable[None]]
-"""
-`bot.call_api` 时执行的函数
-"""
+"""`bot.call_api` 插槽函数"""
 T_CalledAPIHook = Callable[
     ["Bot", Optional[Exception], str, Dict[str, Any], Any], Awaitable[None]
 ]
-"""
-`bot.call_api` 后执行的函数，参数分别为 bot, exception, api, data, result
-"""
+"""`bot.call_api` 后执行的函数，参数分别为 bot, exception, api, data, result"""
 
 T_EventPreProcessor = Callable[..., Union[None, Awaitable[None]]]
-"""
-事件预处理函数 EventPreProcessor 类型
+"""事件预处理函数 EventPreProcessor 类型
 
 依赖参数:
 
@@ -76,8 +67,7 @@ T_EventPreProcessor = Callable[..., Union[None, Awaitable[None]]]
 - DefaultParam: 带有默认值的参数
 """
 T_EventPostProcessor = Callable[..., Union[None, Awaitable[None]]]
-"""
-事件预处理函数 EventPostProcessor 类型
+"""事件预处理函数 EventPostProcessor 类型
 
 依赖参数:
 
@@ -88,8 +78,7 @@ T_EventPostProcessor = Callable[..., Union[None, Awaitable[None]]]
 - DefaultParam: 带有默认值的参数
 """
 T_RunPreProcessor = Callable[..., Union[None, Awaitable[None]]]
-"""
-事件响应器运行前预处理函数 RunPreProcessor 类型
+"""事件响应器运行前预处理函数 RunPreProcessor 类型
 
 依赖参数:
 
@@ -101,8 +90,7 @@ T_RunPreProcessor = Callable[..., Union[None, Awaitable[None]]]
 - DefaultParam: 带有默认值的参数
 """
 T_RunPostProcessor = Callable[..., Union[None, Awaitable[None]]]
-"""
-事件响应器运行前预处理函数 RunPostProcessor 类型，第二个参数为运行时产生的错误（如果存在）
+"""事件响应器运行前预处理函数 RunPostProcessor 类型
 
 依赖参数:
 
@@ -116,8 +104,7 @@ T_RunPostProcessor = Callable[..., Union[None, Awaitable[None]]]
 """
 
 T_RuleChecker = Callable[..., Union[bool, Awaitable[bool]]]
-"""
-RuleChecker 即判断是否响应事件的处理函数。
+"""RuleChecker 即判断是否响应事件的处理函数。
 
 依赖参数:
 
@@ -128,8 +115,7 @@ RuleChecker 即判断是否响应事件的处理函数。
 - DefaultParam: 带有默认值的参数
 """
 T_PermissionChecker = Callable[..., Union[bool, Awaitable[bool]]]
-"""
-RuleChecker 即判断是否响应消息的处理函数。
+"""PermissionChecker 即判断事件是否满足权限的处理函数。
 
 依赖参数:
 
@@ -140,12 +126,9 @@ RuleChecker 即判断是否响应消息的处理函数。
 """
 
 T_Handler = Callable[..., Any]
-"""
-Handler 处理函数。
-"""
+"""Handler 处理函数。"""
 T_TypeUpdater = Callable[..., Union[str, Awaitable[str]]]
-"""
-TypeUpdater 在 Matcher.pause, Matcher.reject 时被运行，用于更新响应的事件类型。默认会更新为 `message`。
+"""TypeUpdater 在 Matcher.pause, Matcher.reject 时被运行，用于更新响应的事件类型。默认会更新为 `message`。
 
 依赖参数:
 
@@ -157,8 +140,7 @@ TypeUpdater 在 Matcher.pause, Matcher.reject 时被运行，用于更新响应
 - DefaultParam: 带有默认值的参数
 """
 T_PermissionUpdater = Callable[..., Union["Permission", Awaitable["Permission"]]]
-"""
-PermissionUpdater 在 Matcher.pause, Matcher.reject 时被运行，用于更新会话对象权限。默认会更新为当前事件的触发对象。
+"""PermissionUpdater 在 Matcher.pause, Matcher.reject 时被运行，用于更新会话对象权限。默认会更新为当前事件的触发对象。
 
 依赖参数:
 
@@ -170,6 +152,4 @@ PermissionUpdater 在 Matcher.pause, Matcher.reject 时被运行，用于更新
 - DefaultParam: 带有默认值的参数
 """
 T_DependencyCache = Dict[Callable[..., Any], "Task[Any]"]
-"""
-依赖缓存, 用于存储依赖函数的返回值
-"""
+"""依赖缓存, 用于存储依赖函数的返回值"""