💡 add docstrings

nonebot/utils.py

@@ -1,4 +1,5 @@
-"""
+"""本模块包含了 NoneBot 的一些工具函数
+
 FrontMatter:
     sidebar_position: 8
     description: nonebot.utils 模块
@@ -36,8 +37,9 @@ V = TypeVar("V")
 
 
 def escape_tag(s: str) -> str:
-    """
-    用于记录带颜色日志时转义 `<tag>` 类型特殊标签
+    """用于记录带颜色日志时转义 `<tag>` 类型特殊标签
+
+    参考: [loguru color 标签](https://loguru.readthedocs.io/en/stable/api/logger.html#color)
 
     参数:
         s: 需要转义的字符串
@@ -48,6 +50,7 @@ def escape_tag(s: str) -> str:
 def generic_check_issubclass(
     cls: Any, class_or_tuple: Union[Type[Any], Tuple[Type[Any], ...]]
 ) -> bool:
+    """检查 cls 是否是 class_or_tuple 中的一个类型子类或"""
     try:
         return issubclass(cls, class_or_tuple)
     except TypeError:
@@ -65,6 +68,7 @@ def generic_check_issubclass(
 
 
 def is_coroutine_callable(call: Callable[..., Any]) -> bool:
+    """检查 call 是否是一个 callable 协程函数"""
     if inspect.isroutine(call):
         return inspect.iscoroutinefunction(call)
     if inspect.isclass(call):
@@ -74,6 +78,7 @@ def is_coroutine_callable(call: Callable[..., Any]) -> bool:
 
 
 def is_gen_callable(call: Callable[..., Any]) -> bool:
+    """检查 call 是否是一个生成器函数"""
     if inspect.isgeneratorfunction(call):
         return True
     func_ = getattr(call, "__call__", None)
@@ -81,6 +86,7 @@ def is_gen_callable(call: Callable[..., Any]) -> bool:
 
 
 def is_async_gen_callable(call: Callable[..., Any]) -> bool:
+    """检查 call 是否是一个异步生成器函数"""
     if inspect.isasyncgenfunction(call):
         return True
     func_ = getattr(call, "__call__", None)
@@ -88,8 +94,7 @@ def is_async_gen_callable(call: Callable[..., Any]) -> bool:
 
 
 def run_sync(call: Callable[P, R]) -> Callable[P, Awaitable[R]]:
-    """
-    一个用于包装 sync function 为 async function 的装饰器
+    """一个用于包装 sync function 为 async function 的装饰器
 
     参数:
         call: 被装饰的同步函数
@@ -109,6 +114,7 @@ def run_sync(call: Callable[P, R]) -> Callable[P, Awaitable[R]]:
 async def run_sync_ctx_manager(
     cm: ContextManager[T],
 ) -> AsyncGenerator[T, None]:
+    """一个用于包装 sync context manager 为 async context manager 的执行函数"""
     try:
         yield await run_sync(cm.__enter__)()
     except Exception as e:
@@ -120,15 +126,14 @@ async def run_sync_ctx_manager(
 
 
 def get_name(obj: Any) -> str:
+    """获取对象的名称"""
     if inspect.isfunction(obj) or inspect.isclass(obj):
         return obj.__name__
     return obj.__class__.__name__
 
 
 class DataclassEncoder(json.JSONEncoder):
-    """
-    在JSON序列化 `Message` (List[Dataclass]) 时使用的 `JSONEncoder`
-    """
+    """在JSON序列化 {re}`nonebot.adapters._message.Message` (List[Dataclass]) 时使用的 `JSONEncoder`"""
 
     @overrides(json.JSONEncoder)
     def default(self, o):
@@ -137,14 +142,18 @@ class DataclassEncoder(json.JSONEncoder):
         return super().default(o)
 
 
-def logger_wrapper(logger_name: str):
-    """
-    用于打印 adapter 的日志。
+def logger_wrapper(logger_name: str) -> Callable[[str, str, Optional[Exception]], None]:
+    """用于打印 adapter 的日志。
 
     参数:
-        level: 日志等级
-        message: 日志信息
-        exception: 异常信息
+        logger_name: adapter 的名称
+
+    返回:
+        日志记录函数
+
+            - level: 日志等级
+            - message: 日志信息
+            - exception: 异常信息
     """
 
     def log(level: str, message: str, exception: Optional[Exception] = None):