💡 add permission docstring

nonebot/permission.py

@@ -1,5 +1,15 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""
+权限
+====
+
+每个 ``Matcher`` 拥有一个 ``Permission`` ，其中是 **异步** ``PermissionChecker`` 的集合，只要有一个 ``PermissionChecker`` 检查结果为 ``True`` 时就会继续运行。
+
+\:\:\:tip 提示
+``PermissionChecker`` 既可以是 async function 也可以是 sync function
+\:\:\:
+"""
 
 import asyncio
 
@@ -12,9 +22,28 @@ class Permission:
 
     def __init__(self, *checkers: Callable[[Bot, Event],
                                            Awaitable[bool]]) -> None:
+        """
+        :参数:
+          * ``*checkers: Callable[[Bot, Event], Awaitable[bool]]``: **异步** PermissionChecker
+        """
         self.checkers = set(checkers)
+        """
+        :说明:
+          存储 ``PermissionChecker``
+        :类型:
+          * ``Set[Callable[[Bot, Event], Awaitable[bool]]]``
+        """
 
     async def __call__(self, bot: Bot, event: Event) -> bool:
+        """
+        :说明:
+          检查是否满足某个权限
+        :参数:
+          * ``bot: Bot``: Bot 对象
+          * ``event: Event``: Event 对象
+        :返回:
+          - ``bool``
+        """
         if not self.checkers:
             return True
         results = await asyncio.gather(
@@ -53,12 +82,31 @@ async def _metaevent(bot: Bot, event: Event) -> bool:
 
 
 MESSAGE = Permission(_message)
+"""
+- **说明**: 匹配任意 ``message`` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 message type 的 Matcher。
+"""
 NOTICE = Permission(_notice)
+"""
+- **说明**: 匹配任意 ``notice`` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 notice type 的 Matcher。
+"""
 REQUEST = Permission(_request)
+"""
+- **说明**: 匹配任意 ``request`` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 request type 的 Matcher。
+"""
 METAEVENT = Permission(_metaevent)
+"""
+- **说明**: 匹配任意 ``meta_event`` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 meta_event type 的 Matcher。
+"""
 
 
 def USER(*user: int, perm: Permission = Permission()):
+    """
+    :说明:
+      在白名单内且满足 perm
+    :参数:
+      * ``*user: int``: 白名单
+      * ``perm: Permission``: 需要同时满足的权限
+    """
 
     async def _user(bot: Bot, event: Event) -> bool:
         return event.type == "message" and event.user_id in user and await perm(
@@ -87,9 +135,21 @@ async def _private_other(bot: Bot, event: Event) -> bool:
 
 
 PRIVATE = Permission(_private)
+"""
+- **说明**: 匹配任意私聊消息类型事件
+"""
 PRIVATE_FRIEND = Permission(_private_friend)
+"""
+- **说明**: 匹配任意好友私聊消息类型事件
+"""
 PRIVATE_GROUP = Permission(_private_group)
+"""
+- **说明**: 匹配任意群临时私聊消息类型事件
+"""
 PRIVATE_OTHER = Permission(_private_other)
+"""
+- **说明**: 匹配任意其他私聊消息类型事件
+"""
 
 
 async def _group(bot: Bot, event: Event) -> bool:
@@ -112,9 +172,25 @@ async def _group_owner(bot: Bot, event: Event) -> bool:
 
 
 GROUP = Permission(_group)
+"""
+- **说明**: 匹配任意群聊消息类型事件
+"""
 GROUP_MEMBER = Permission(_group_member)
+"""
+- **说明**: 匹配任意群员群聊消息类型事件
+
+\:\:\:warning 警告
+该权限通过 event.sender 进行判断且不包含管理员以及群主！
+\:\:\:
+"""
 GROUP_ADMIN = Permission(_group_admin)
+"""
+- **说明**: 匹配任意群管理员群聊消息类型事件
+"""
 GROUP_OWNER = Permission(_group_owner)
+"""
+- **说明**: 匹配任意群主群聊消息类型事件
+"""
 
 
 async def _superuser(bot: Bot, event: Event) -> bool:
@@ -122,4 +198,10 @@ async def _superuser(bot: Bot, event: Event) -> bool:
 
 
 SUPERUSER = Permission(_superuser)
+"""
+- **说明**: 匹配任意超级用户消息类型事件
+"""
 EVERYBODY = MESSAGE
+"""
+- **说明**: 匹配任意消息类型事件
+"""

nonebot/rule.py

@@ -4,7 +4,7 @@
 规则
 ====
 
-每个 ``Matcher`` 拥有一个 ``Rule`` ，其中是 ``RuleChecker`` 的集合，只有当所有 ``RuleChecker`` 检查结果为 ``True`` 时继续运行。
+每个 ``Matcher`` 拥有一个 ``Rule`` ，其中是 **异步** ``RuleChecker`` 的集合，只有当所有 ``RuleChecker`` 检查结果为 ``True`` 时继续运行。
 
 \:\:\:tip 提示
 ``RuleChecker`` 既可以是 async function 也可以是 sync function