From 733c95116396a8bc0c8b2eb9e7635d2b9e0f6ba8 Mon Sep 17 00:00:00 2001
From: Rapptz <rapptz@gmail.com>
Date: Mon, 16 Jan 2023 20:59:21 -0500
Subject: [PATCH] Formally document utils.maybe_coroutine

---
 discord/utils.py | 25 +++++++++++++++++++++++++
 docs/api.rst     |  2 ++
 2 files changed, 27 insertions(+)

diff --git a/discord/utils.py b/discord/utils.py
index cb832131b..b4c756563 100644
--- a/discord/utils.py
+++ b/discord/utils.py
@@ -98,6 +98,7 @@ __all__ = (
     'remove_markdown',
     'escape_markdown',
     'escape_mentions',
+    'maybe_coroutine',
     'as_chunks',
     'format_dt',
     'set_target',
@@ -742,6 +743,30 @@ def _parse_ratelimit_header(request: Any, *, use_clock: bool = False) -> float:
 
 
 async def maybe_coroutine(f: MaybeAwaitableFunc[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
+    r"""|coro|
+
+    A helper function that will await the result of a function if it's a coroutine
+    or return the result if it's not.
+
+    This is useful for functions that may or may not be coroutines.
+
+    .. versionadded:: 2.2
+
+    Parameters
+    -----------
+    f: Callable[..., Any]
+        The function or coroutine to call.
+    \*args
+        The arguments to pass to the function.
+    \*\*kwargs
+        The keyword arguments to pass to the function.
+
+    Returns
+    --------
+    Any
+        The result of the function or coroutine.
+    """
+
     value = f(*args, **kwargs)
     if _isawaitable(value):
         return await value
diff --git a/docs/api.rst b/docs/api.rst
index a15ba1a29..871f72f4f 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -1444,6 +1444,8 @@ Utility Functions
 
 .. autofunction:: discord.utils.setup_logging
 
+.. autofunction:: discord.utils.maybe_coroutine
+
 .. autofunction:: discord.utils.snowflake_time
 
 .. autofunction:: discord.utils.time_snowflake