💡 📝 add some comments in code, add document build struct for mirai adapter

docs_build/README.rst

@@ -18,3 +18,4 @@ NoneBot Api Reference
   - `nonebot.adapters <adapters/>`_
   - `nonebot.adapters.cqhttp <adapters/cqhttp.html>`_
   - `nonebot.adapters.ding <adapters/ding.html>`_
+  - `nonebot.adapters.mirai <adapters/mirai.html>`_

docs_build/adapters/mirai.rst

@@ -0,0 +1,72 @@
+---
+contentSidebar: true
+sidebarDepth: 0
+---
+
+NoneBot.adapters.mirai 模块
+===========================
+
+.. automodule:: nonebot.adapters.mirai
+
+NoneBot.adapters.mirai.bot 模块
+=====================================
+
+.. automodule:: nonebot.adapters.mirai.bot
+   :members:
+   :show-inheritance:
+
+NoneBot.adapters.mirai.bot_ws 模块
+=====================================
+
+.. automodule:: nonebot.adapters.mirai.bot_ws
+   :members:
+   :show-inheritance:
+
+NoneBot.adapters.mirai.config 模块
+=====================================
+
+.. automodule:: nonebot.adapters.mirai.config
+   :members:
+   :show-inheritance:
+
+NoneBot.adapters.mirai.message 模块
+====================================
+
+.. automodule:: nonebot.adapters.mirai.message
+   :members:
+   :show-inheritance:
+
+NoneBot.adapters.mirai.event 模块
+====================================
+
+.. automodule:: nonebot.adapters.mirai.event
+   :members:
+   :show-inheritance:
+
+NoneBot.adapters.mirai.event.base 模块
+====================================
+
+.. automodule:: nonebot.adapters.mirai.event.base
+   :members:
+   :show-inheritance:
+
+NoneBot.adapters.mirai.event.message 模块
+====================================
+
+.. automodule:: nonebot.adapters.mirai.event.message
+   :members:
+   :show-inheritance:
+
+NoneBot.adapters.mirai.event.notice 模块
+====================================
+
+.. automodule:: nonebot.adapters.mirai.event.notice
+   :members:
+   :show-inheritance:
+
+NoneBot.adapters.mirai.event.request 模块
+====================================
+
+.. automodule:: nonebot.adapters.mirai.event.request
+   :members:
+   :show-inheritance:

nonebot/adapters/mirai/bot.py

@@ -22,13 +22,13 @@ from .message import MessageChain, MessageSegment
 
 class ActionFailed(BaseActionFailed):
 
-    def __init__(self, code: int, message: str = ''):
+    def __init__(self, **kwargs):
         super().__init__('mirai')
-        self.code = code
+        self.data = kwargs.copy()
-        self.message = message
 
     def __repr__(self):
-        return f"{self.__class__.__name__}(code={self.code}, message={self.message!r})"
+        return self.__class__.__name__ + '(%s)' % ', '.join(
+            map(lambda m: '%s=%r' % m, self.data.items()))
 
 
 class SessionManager:
@@ -44,7 +44,7 @@ class SessionManager:
         logger.opt(colors=True).debug('Mirai API returned data: '
                                       f'<y>{escape_tag(str(data))}</y>')
         if code != 0:
-            raise ActionFailed(code, message=data['msg'])
+            raise ActionFailed(**data)
         return data
 
     async def post(self,
@@ -310,7 +310,7 @@ class MiraiBot(BaseBot):
         return await self.api.post('recall', params={'target': target})
 
     async def send_image_message(self, target: int, qq: int, group: int,
-                                 urls: List[str]):
+                                 urls: List[str]) -> List[str]:
         """
         :说明:
 
@@ -321,14 +321,14 @@ class MiraiBot(BaseBot):
 
         :参数:
 
-          * ``target: int``: [description]
+          * ``target: int``: 发送对象的QQ号或群号，可能存在歧义
-          * ``qq: int``: [description]
+          * ``qq: int``: 发送对象的QQ号
-          * ``group: int``: [description]
+          * ``group: int``: 发送对象的群号
-          * ``urls: List[str]``: [description]
+          * ``urls: List[str]``: 是一个url字符串构成的数组
 
         :返回:
 
-          - ``[type]``: [description]
+          - ``List[str]``: 一个包含图片imageId的数组
         """
         return await self.api.post('sendImageMessage',
                                    params={
@@ -336,48 +336,174 @@ class MiraiBot(BaseBot):
                                        'qq': qq,
                                        'group': group,
                                        'urls': urls
-                                   })
+                                   })  # type: ignore
 
     async def upload_image(self, type: str, img: BytesIO):
+        """
+        :说明:
+
+           使用此方法上传图片文件至服务器并返回Image_id
+
+        :参数:
+
+          * ``type: str``: "friend" 或 "group" 或 "temp"
+          * ``img: BytesIO``: 图片的BytesIO对象
+
+        :返回:
+
+          - ``Any``: API 调用返回数据
+        """
         return await self.api.upload('uploadImage',
                                      type=type,
                                      file=('img', img))
 
     async def upload_voice(self, type: str, voice: BytesIO):
+        """
+        :说明:
+
+          使用此方法上传语音文件至服务器并返回voice_id
+
+        :参数:
+
+          * ``type: str``: 当前仅支持 "group"
+          * ``voice: BytesIO``: 语音的BytesIO对象
+
+        :返回:
+
+          - ``Any``: API 调用返回数据
+        """
         return await self.api.upload('uploadVoice',
                                      type=type,
                                      file=('voice', voice))
 
-    async def fetch_message(self):
+    async def fetch_message(self, count: int = 10):
-        return await self.api.request('fetchMessage')
+        """
+        :说明:
 
-    async def fetch_latest_message(self):
+          使用此方法获取bot接收到的最老消息和最老各类事件
-        return await self.api.request('fetchLatestMessage')
+          (会从MiraiApiHttp消息记录中删除)
 
-    async def peek_message(self, count: int):
+        :参数:
+
+          * ``count: int``: 获取消息和事件的数量
+        """
+        return await self.api.request('fetchMessage', params={'count': count})
+
+    async def fetch_latest_message(self, count: int = 10):
+        """
+        :说明:
+
+          使用此方法获取bot接收到的最新消息和最新各类事件
+          (会从MiraiApiHttp消息记录中删除)
+
+        :参数:
+
+          * ``count: int``: 获取消息和事件的数量
+        """
+        return await self.api.request('fetchLatestMessage',
+                                      params={'count': count})
+
+    async def peek_message(self, count: int = 10):
+        """
+        :说明:
+
+          使用此方法获取bot接收到的最老消息和最老各类事件
+          (不会从MiraiApiHttp消息记录中删除) 
+
+        :参数:
+
+          * ``count: int``: 获取消息和事件的数量
+        """
         return await self.api.request('peekMessage', params={'count': count})
 
-    async def peek_latest_message(self, count: int):
+    async def peek_latest_message(self, count: int = 10):
+        """
+        :说明:
+
+          使用此方法获取bot接收到的最新消息和最新各类事件
+          (不会从MiraiApiHttp消息记录中删除)
+        
+        :参数:
+
+          * ``count: int``: 获取消息和事件的数量
+        """
         return await self.api.request('peekLatestMessage',
                                       params={'count': count})
 
     async def messsage_from_id(self, id: int):
+        """
+        :说明:
+
+          通过messageId获取一条被缓存的消息
+          使用此方法获取bot接收到的消息和各类事件
+
+        :参数:
+
+          * ``id: int``: 获取消息的message_id
+        """
         return await self.api.request('messageFromId', params={'id': id})
 
     async def count_message(self):
+        """
+        :说明:
+
+          使用此方法获取bot接收并缓存的消息总数，注意不包含被删除的
+        """
         return await self.api.request('countMessage')
 
     async def friend_list(self) -> List[Dict[str, Any]]:
+        """
+        :说明:
+
+          使用此方法获取bot的好友列表
+
+        :返回:
+
+          - ``List[Dict[str, Any]]``: 返回的好友列表数据
+        """
         return await self.api.request('friendList')  # type: ignore
 
     async def group_list(self) -> List[Dict[str, Any]]:
+        """
+        :说明:
+
+          使用此方法获取bot的群列表
+
+        :返回:
+
+          - ``List[Dict[str, Any]]``: 返回的群列表数据
+        """
         return await self.api.request('groupList')  # type: ignore
 
     async def member_list(self, target: int) -> List[Dict[str, Any]]:
+        """
+        :说明:
+
+          使用此方法获取bot指定群种的成员列表
+
+        :参数:
+
+          * ``target: int``: 指定群的群号
+
+        :返回:
+
+          - ``List[Dict[str, Any]]``: 返回的群成员列表数据
+        """
         return await self.api.request('memberList',
                                       params={'target': target})  # type: ignore
 
     async def mute(self, target: int, member_id: int, time: int):
+        """
+        :说明:
+
+          使用此方法指定群禁言指定群员（需要有相关权限）
+
+        :参数:
+
+          * ``target: int``: 指定群的群号
+          * ``member_id: int``: 指定群员QQ号
+          * ``time: int``: 禁言时长，单位为秒，最多30天
+        """
         return await self.api.post('mute',
                                    params={
                                        'target': target,
@@ -386,6 +512,16 @@ class MiraiBot(BaseBot):
                                    })
 
     async def unmute(self, target: int, member_id: int):
+        """
+        :说明:
+
+          使用此方法指定群解除群成员禁言（需要有相关权限）
+
+        :参数:
+
+          * ``target: int``: 指定群的群号
+          * ``member_id: int``: 指定群员QQ号
+        """
         return await self.api.post('unmute',
                                    params={
                                        'target': target,
@@ -393,6 +529,17 @@ class MiraiBot(BaseBot):
                                    })
 
     async def kick(self, target: int, member_id: int, msg: str):
+        """
+        :说明:
+
+          使用此方法移除指定群成员（需要有相关权限）
+
+        :参数:
+
+          * ``target: int``: 指定群的群号
+          * ``member_id: int``: 指定群员QQ号
+          * ``msg: str``: 信息
+        """
         return await self.api.post('kick',
                                    params={
                                        'target': target,
@@ -401,18 +548,77 @@ class MiraiBot(BaseBot):
                                    })
 
     async def quit(self, target: int):
+        """
+        :说明:
+
+          使用此方法使Bot退出群聊 
+
+        :参数:
+
+          * ``target: int``: 退出的群号
+        """
         return await self.api.post('quit', params={'target': target})
 
     async def mute_all(self, target: int):
+        """
+        :说明:
+
+          使用此方法令指定群进行全体禁言（需要有相关权限）
+
+        :参数:
+
+          * ``target: int``: 指定群的群号
+        """
         return await self.api.post('muteAll', params={'target': target})
 
     async def unmute_all(self, target: int):
+        """
+        :说明:
+
+          使用此方法令指定群解除全体禁言（需要有相关权限）
+
+        :参数:
+
+          * ``target: int``: 指定群的群号
+        """
         return await self.api.post('unmuteAll', params={'target': target})
 
     async def group_config(self, target: int):
+        """
+        :说明:
+
+          使用此方法获取群设置
+
+        :参数:
+
+          * ``target: int``: 指定群的群号
+
+        :返回:
+
+        .. code-block:: json
+
+            {
+                "name": "群名称",
+                "announcement": "群公告",
+                "confessTalk": true,
+                "allowMemberInvite": true,
+                "autoApprove": true,
+                "anonymousChat": true
+            }
+        """
         return await self.api.request('groupConfig', params={'target': target})
 
     async def modify_group_config(self, target: int, config: Dict[str, Any]):
+        """
+        :说明:
+
+          使用此方法修改群设置（需要有相关权限）
+
+        :参数:
+
+          * ``target: int``: 指定群的群号
+          * ``config: Dict[str, Any]``: 群设置, 格式见 ``group_config`` 的返回值
+        """
         return await self.api.post('groupConfig',
                                    params={
                                        'target': target,
@@ -420,6 +626,25 @@ class MiraiBot(BaseBot):
                                    })
 
     async def member_info(self, target: int, member_id: int):
+        """
+        :说明:
+
+          使用此方法获取群员资料
+
+        :参数:
+
+          * ``target: int``: 指定群的群号
+          * ``member_id: int``: 群员QQ号
+
+        :返回:
+
+        .. code-block:: json
+
+            {
+                "name": "群名片",
+                "specialTitle": "群头衔"
+            }
+        """
         return await self.api.request('memberInfo',
                                       params={
                                           'target': target,
@@ -428,6 +653,21 @@ class MiraiBot(BaseBot):
 
     async def modify_member_info(self, target: int, member_id: int,
                                  info: Dict[str, Any]):
+        """
+        :说明:
+
+          使用此方法修改群员资料（需要有相关权限）
+
+        :参数:
+
+          * ``target: int``: 指定群的群号
+          * ``member_id: int``: 群员QQ号
+          * ``info: Dict[str, Any]``: 群员资料, 格式见 ``member_info`` 的返回值
+
+        :返回:
+
+          - ``[type]``: [description]
+        """
         return await self.api.post('memberInfo',
                                    params={
                                        'target': target,

nonebot/adapters/mirai/event/request.py

@@ -20,6 +20,15 @@ class NewFriendRequestEvent(RequestEvent):
     group_id: int = Field(0, alias='groupId')
 
     async def approve(self, bot: "Bot"):
+        """
+        :说明:
+
+          通过此人的好友申请
+
+        :参数:
+
+          * ``bot: Bot``: 当前的 ``Bot`` 对象
+        """
         return await bot.api.post('/resp/newFriendRequestEvent',
                                   params={
                                       'eventId': self.event_id,
@@ -32,6 +41,23 @@ class NewFriendRequestEvent(RequestEvent):
                      bot: "Bot",
                      operate: Literal[1, 2] = 1,
                      message: str = ''):
+        """
+        :说明:
+
+          拒绝此人的好友申请 
+
+        :参数:
+
+          * ``bot: Bot``: 当前的 ``Bot`` 对象
+          * ``operate: Literal[1, 2]``: 响应的操作类型
+            - ``1``: 拒绝添加好友
+            - ``2``: 拒绝添加好友并添加黑名单，不再接收该用户的好友申请
+          * ``message: str``: 回复的信息
+
+        :返回:
+
+          - ``[type]``: [description]
+        """
         assert operate > 0
         return await bot.api.post('/resp/newFriendRequestEvent',
                                   params={
@@ -49,6 +75,15 @@ class MemberJoinRequestEvent(RequestEvent):
     group_name: str = Field(alias='groupName')
 
     async def approve(self, bot: "Bot"):
+        """
+        :说明:
+
+          通过此人的加群申请
+
+        :参数:
+
+          * ``bot: Bot``: 当前的 ``Bot`` 对象
+        """
         return await bot.api.post('/resp/memberJoinRequestEvent',
                                   params={
                                       'eventId': self.event_id,
@@ -61,6 +96,21 @@ class MemberJoinRequestEvent(RequestEvent):
                      bot: "Bot",
                      operate: Literal[1, 2, 3, 4] = 1,
                      message: str = ''):
+        """
+        :说明:
+
+          拒绝(忽略)此人的加群申请
+
+        :参数:
+
+          * ``bot: Bot``: 当前的 ``Bot`` 对象
+          * ``operate: Literal[1, 2, 3, 4]``: 响应的操作类型
+            - ``1``: 拒绝入群
+            - ``2``: 忽略请求
+            - ``3``: 拒绝入群并添加黑名单，不再接收该用户的入群申请
+            - ``4``: 忽略入群并添加黑名单，不再接收该用户的入群申请
+          * ``message: str``: 回复的信息
+        """
         assert operate > 0
         return await bot.api.post('/resp/memberJoinRequestEvent',
                                   params={
@@ -78,6 +128,15 @@ class BotInvitedJoinGroupRequestEvent(RequestEvent):
     group_name: str = Field(alias='groupName')
 
     async def approve(self, bot: "Bot"):
+        """
+        :说明:
+
+          通过这份被邀请入群申请 
+
+        :参数:
+
+          * ``bot: Bot``: 当前的 ``Bot`` 对象
+        """
         return await bot.api.post('/resp/botInvitedJoinGroupRequestEvent',
                                   params={
                                       'eventId': self.event_id,
@@ -87,6 +146,16 @@ class BotInvitedJoinGroupRequestEvent(RequestEvent):
                                   })
 
     async def reject(self, bot: "Bot", message: str = ""):
+        """
+        :说明:
+
+          拒绝这份被邀请入群申请 
+
+        :参数:
+
+          * ``bot: Bot``: 当前的 ``Bot`` 对象
+          * ``message: str``: 邀请消息
+        """
         return await bot.api.post('/resp/botInvitedJoinGroupRequestEvent',
                                   params={
                                       'eventId': self.event_id,