💡 add docstrings

nonebot/plugin/load.py

@@ -1,3 +1,9 @@
+"""本模块定义插件加载接口。
+
+FrontMatter:
+    sidebar_position: 1
+    description: nonebot.plugin.load 模块
+"""
 import json
 import warnings
 from typing import Set, Iterable, Optional
@@ -11,8 +17,7 @@ from .plugin import Plugin, get_plugin
 
 
 def load_plugin(module_path: str) -> Optional[Plugin]:
-    """
-    使用 `PluginManager` 加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。
+    """加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。
 
     参数:
         module_path: 插件名称 `path.to.your.plugin`
@@ -24,11 +29,10 @@ def load_plugin(module_path: str) -> Optional[Plugin]:
 
 
 def load_plugins(*plugin_dir: str) -> Set[Plugin]:
-    """
-    导入目录下多个插件，以 `_` 开头的插件不会被导入！
+    """导入文件夹下多个插件，以 `_` 开头的插件不会被导入!
 
     参数:
-        plugin_dir: 插件路径
+        plugin_dir: 文件夹路径
     """
     manager = PluginManager(search_path=plugin_dir)
     _managers.append(manager)
@@ -38,12 +42,11 @@ def load_plugins(*plugin_dir: str) -> Set[Plugin]:
 def load_all_plugins(
     module_path: Iterable[str], plugin_dir: Iterable[str]
 ) -> Set[Plugin]:
-    """
-    导入指定列表中的插件以及指定目录下多个插件，以 `_` 开头的插件不会被导入！
+    """导入指定列表中的插件以及指定目录下多个插件，以 `_` 开头的插件不会被导入!
 
     参数:
         module_path: 指定插件集合
-        plugin_dir: 指定插件路径集合
+        plugin_dir: 指定文件夹路径集合
     """
     manager = PluginManager(module_path, plugin_dir)
     _managers.append(manager)
@@ -51,12 +54,23 @@ def load_all_plugins(
 
 
 def load_from_json(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
-    """
-    导入指定 json 文件中的 `plugins` 以及 `plugin_dirs` 下多个插件，以 `_` 开头的插件不会被导入！
+    """导入指定 json 文件中的 `plugins` 以及 `plugin_dirs` 下多个插件，以 `_` 开头的插件不会被导入!
 
     参数:
         file_path: 指定 json 文件路径
         encoding: 指定 json 文件编码
+
+    用法:
+        ```json title=plugins.json
+        {
+            "plugins": ["some_plugin"],
+            "plugin_dirs": ["some_dir"]
+        }
+        ```
+
+        ```python
+        nonebot.load_from_json("plugins.json")
+        ```
     """
     with open(file_path, "r", encoding=encoding) as f:
         data = json.load(f)
@@ -68,13 +82,22 @@ def load_from_json(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
 
 
 def load_from_toml(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
-    """
-    导入指定 toml 文件 `[tool.nonebot]` 中的 `plugins` 以及 `plugin_dirs` 下多个插件，
-      以 `_` 开头的插件不会被导入！
+    """导入指定 toml 文件 `[tool.nonebot]` 中的 `plugins` 以及 `plugin_dirs` 下多个插件，以 `_` 开头的插件不会被导入!
 
     参数:
         file_path: 指定 toml 文件路径
         encoding: 指定 toml 文件编码
+
+    用法:
+        ```toml title=pyproject.toml
+        [tool.nonebot]
+        plugins = ["some_plugin"]
+        plugin_dirs = ["some_dir"]
+        ```
+
+        ```python
+        nonebot.load_from_toml("pyproject.toml")
+        ```
     """
     with open(file_path, "r", encoding=encoding) as f:
         data = tomlkit.parse(f.read())  # type: ignore
@@ -97,25 +120,30 @@ def load_from_toml(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
 
 
 def load_builtin_plugin(name: str) -> Optional[Plugin]:
-    """
-    导入 NoneBot 内置插件
+    """导入 NoneBot 内置插件。
+
+    参数:
+        name: 插件名称
     """
     return load_plugin(f"nonebot.plugins.{name}")
 
 
 def load_builtin_plugins(*plugins) -> Set[Plugin]:
-    """
-    导入多个 NoneBot 内置插件
+    """导入多个 NoneBot 内置插件。
+
+    参数:
+        plugins: 插件名称列表
     """
     return load_all_plugins([f"nonebot.plugins.{p}" for p in plugins], [])
 
 
 def require(name: str) -> Export:
-    """
-    获取一个插件的导出内容
+    """获取一个插件的导出内容。
+
+    如果为 `load_plugins` 文件夹导入的插件，则为文件(夹)名。
 
     参数:
-        name: 插件名，与 `load_plugin` 参数一致。如果为 `load_plugins` 导入的插件，则为文件(夹)名。
+        name: 插件名，即 {ref}`nonebot.plugin.plugin.Plugin.name`。
 
     异常:
         RuntimeError: 插件无法加载