💡 add cqhttp docstring

docs/.vuepress/config.js

@@ -119,6 +119,10 @@ module.exports = context => ({
                 {
                   title: "nonebot.exception 模块",
                   path: "exception"
+                },
+                {
+                  title: "nonebot.adapters.cqhttp 模块",
+                  path: "adapters/cqhttp"
                 }
               ]
             }

docs/api/README.md

@@ -29,3 +29,6 @@
 
 
     * [nonebot.exception](exception.html)
+
+
+    * [nonebot.adapters.cqhttp](adapters/cqhttp.html)

docs/api/adapters/cqhttp.md

@@ -0,0 +1,274 @@
+---
+contentSidebar: true
+sidebarDepth: 0
+---
+
+# NoneBot.adapters.cqhttp 模块
+
+## CQHTTP (OneBot) v11 协议适配
+
+协议详情请看: [CQHTTP](http://cqhttp.cc/) | [OneBot](https://github.com/howmanybots/onebot)
+
+
+## `log(level, message)`
+
+
+* **说明**
+
+    用于打印 CQHTTP 日志。
+
+
+
+* **参数**
+
+    
+    * `level: str`: 日志等级
+
+
+    * `message: str`: 日志信息
+
+
+
+## `escape(s, *, escape_comma=True)`
+
+
+* **说明**
+
+    对字符串进行 CQ 码转义。
+
+
+
+* **参数**
+
+    
+    * `s: str`: 需要转义的字符串
+
+
+    * `escape_comma: bool`: 是否转义逗号（`,`）。
+
+
+
+## `unescape(s)`
+
+
+* **说明**
+
+    对字符串进行 CQ 码去转义。
+
+
+
+* **参数**
+
+    
+    * `s: str`: 需要转义的字符串
+
+
+
+## `_b2s(b)`
+
+转换布尔值为字符串。
+
+
+## _async_ `_check_reply(bot, event)`
+
+
+* **说明**
+
+    检查消息中存在的回复，去除并赋值 `event.reply`, `event.to_me`
+
+
+
+* **参数**
+
+    
+    * `bot: Bot`: Bot 对象
+
+
+    * `event: Event`: Event 对象
+
+
+
+## `_check_at_me(bot, event)`
+
+
+* **说明**
+
+    检查消息开头或结尾是否存在 @机器人，去除并赋值 `event.to_me`
+
+
+
+* **参数**
+
+    
+    * `bot: Bot`: Bot 对象
+
+
+    * `event: Event`: Event 对象
+
+
+
+## `_check_nickname(bot, event)`
+
+
+* **说明**
+
+    检查消息开头是否存在，去除并赋值 `event.to_me`
+
+
+
+* **参数**
+
+    
+    * `bot: Bot`: Bot 对象
+
+
+    * `event: Event`: Event 对象
+
+
+
+## `_handle_api_result(result)`
+
+
+* **说明**
+
+    处理 API 请求返回值。
+
+
+
+* **参数**
+
+    
+    * `result: Optional[Dict[str, Any]]`: API 返回数据
+
+
+
+* **返回**
+
+    
+    * `Any`: API 调用返回数据
+
+
+
+* **异常**
+
+    
+    * `ActionFailed`: API 调用失败
+
+
+
+## _class_ `Bot`
+
+基类：`nonebot.adapters.BaseBot`
+
+CQHTTP 协议 Bot 适配
+
+
+### _property_ `type`
+
+
+* 返回: `"cqhttp"`
+
+
+### _async_ `handle_message(message)`
+
+
+* **说明**
+
+    调用 [_check_reply](#async-check-reply-bot-event), [_check_at_me](#check-at-me-bot-event), [_check_nickname](#check-nickname-bot-event) 处理事件并转换为 [Event](#class-event)
+
+
+
+### _async_ `call_api(api, **data)`
+
+
+* **说明**
+
+    调用 CQHTTP 协议 API
+
+
+
+* **参数**
+
+    
+    * `api: str`: API 名称
+
+
+    * `**data: Any`: API 参数
+
+
+
+* **返回**
+
+    
+    * `Any`: API 调用返回数据
+
+
+
+* **异常**
+
+    
+    * `NetworkError`: 网络错误
+
+
+    * `ActionFailed`: API 调用失败
+
+
+
+### _async_ `send(event, message, at_sender=False, **kwargs)`
+
+
+* **说明**
+
+    根据 `event`  向触发事件的主体发送消息。
+
+
+
+* **参数**
+
+    
+    * `event: Event`: Event 对象
+
+
+    * `message: Union[str, Message, MessageSegment]`: 要发送的消息
+
+
+    * `at_sender: bool`: 是否 @ 事件主体
+
+
+    * `**kwargs`: 覆盖默认参数
+
+
+
+* **返回**
+
+    
+    * `Any`: API 调用返回数据
+
+
+
+* **异常**
+
+    
+    * `ValueError`: 缺少 `user_id`, `group_id`
+
+
+    * `NetworkError`: 网络错误
+
+
+    * `ActionFailed`: API 调用失败
+
+
+
+## _class_ `Event`
+
+基类：`nonebot.adapters.BaseEvent`
+
+
+## _class_ `MessageSegment`
+
+基类：`nonebot.adapters.BaseMessageSegment`
+
+
+## _class_ `Message`
+
+基类：`nonebot.adapters.BaseMessage`

docs_build/README.rst

@@ -11,3 +11,4 @@ NoneBot Api Reference
   - `nonebot.permission <permission.html>`_
   - `nonebot.utils <utils.html>`_
   - `nonebot.exception <exception.html>`_
+  - `nonebot.adapters.cqhttp <adapters/cqhttp.html>`_

docs_build/adapters/cqhttp.rst

@@ -0,0 +1,12 @@
+---
+contentSidebar: true
+sidebarDepth: 0
+---
+
+NoneBot.adapters.cqhttp 模块
+=================
+
+.. automodule:: nonebot.adapters.cqhttp
+   :members:
+   :private-members:
+   :show-inheritance:

nonebot/adapters/cqhttp.py

@@ -199,7 +199,8 @@ def _check_nickname(bot: "Bot", event: "Event"):
             first_msg_seg.data["text"] = first_text[m.end():]
 
 
-def _handle_api_result(result: Optional[Dict[str, Any]]) -> Any:
+def _handle_api_result(
+        result: Optional[Dict[str, Any]]) -> Union[Any, NoReturn]:
     """
     :说明:
 
@@ -208,6 +209,14 @@ def _handle_api_result(result: Optional[Dict[str, Any]]) -> Any:
     :参数:
 
       * ``result: Optional[Dict[str, Any]]``: API 返回数据
+
+    :返回:
+
+        - ``Any``: API 调用返回数据
+
+    :异常:
+
+        - ``ActionFailed``: API 调用失败
     """
     if isinstance(result, dict):
         if result.get("status") == "failed":
@@ -246,6 +255,9 @@ class ResultStore:
 
 
 class Bot(BaseBot):
+    """
+    CQHTTP 协议 Bot 适配
+    """
 
     def __init__(self,
                  driver: Driver,
@@ -266,10 +278,18 @@ class Bot(BaseBot):
     @property
     @overrides(BaseBot)
     def type(self) -> str:
+        """
+        - 返回: ``"cqhttp"``
+        """
         return "cqhttp"
 
     @overrides(BaseBot)
     async def handle_message(self, message: dict):
+        """
+        :说明:
+
+          调用 `_check_reply <#async-check-reply-bot-event>`_, `_check_at_me <#check-at-me-bot-event>`_, `_check_nickname <#check-nickname-bot-event>`_ 处理事件并转换为 `Event <#class-event>`_
+        """
         if not message:
             return
 
@@ -293,6 +313,25 @@ class Bot(BaseBot):
 
     @overrides(BaseBot)
     async def call_api(self, api: str, **data) -> Union[Any, NoReturn]:
+        """
+        :说明:
+
+          调用 CQHTTP 协议 API
+
+        :参数:
+
+          * ``api: str``: API 名称
+          * ``**data: Any``: API 参数
+
+        :返回:
+
+          - ``Any``: API 调用返回数据
+
+        :异常:
+
+          - ``NetworkError``: 网络错误
+          - ``ActionFailed``: API 调用失败
+        """
         if "self_id" in data:
             self_id = data.pop("self_id")
             if self_id:
@@ -341,12 +380,36 @@ class Bot(BaseBot):
                 raise NetworkError("HTTP request failed")
 
     @overrides(BaseBot)
-    async def send(self, event: "Event", message: Union[str, "Message",
-                                                        "MessageSegment"],
+    async def send(self,
+                   event: "Event",
+                   message: Union[str, "Message", "MessageSegment"],
+                   at_sender: bool = False,
                    **kwargs) -> Union[Any, NoReturn]:
+        """
+        :说明:
+
+          根据 ``event``  向触发事件的主体发送消息。
+
+        :参数:
+
+          * ``event: Event``: Event 对象
+          * ``message: Union[str, Message, MessageSegment]``: 要发送的消息
+          * ``at_sender: bool``: 是否 @ 事件主体
+          * ``**kwargs``: 覆盖默认参数
+
+        :返回:
+
+          - ``Any``: API 调用返回数据
+
+        :异常:
+
+          - ``ValueError``: 缺少 ``user_id``, ``group_id``
+          - ``NetworkError``: 网络错误
+          - ``ActionFailed``: API 调用失败
+        """
         msg = message if isinstance(message, Message) else Message(message)
 
-        at_sender = kwargs.pop("at_sender", False) and bool(event.user_id)
+        at_sender = at_sender and bool(event.user_id)
 
         params = {}
         if event.user_id: