reword docstrings

Co-authored-by: MarkKoz <[email protected]>

3 files changed, 11 insertions, 14 deletions

diff --git a/botcore/utils/cooldown.py b/botcore/utils/cooldown.py
index a06dce46..9e79e48a 100644
--- a/botcore/utils/cooldown.py
+++ b/botcore/utils/cooldown.py
@@ -70,9 +70,9 @@ class _CommandCooldownManager:
     """
     Manage invocation cooldowns for a command through the arguments the command is called with.
 
-    A cooldown is set through `set_cooldown` for a channel with the given `call_arguments`,
-    if `is_on_cooldown` is checked within `cooldown_duration` seconds
-    of the call to `set_cooldown` with the same arguments, True is returned.
+    Use `set_cooldown` to set a cooldown,
+    and `is_on_cooldown` to check for a cooldown for a channel with the given arguments.
+    A cooldown lasts for `cooldown_duration` seconds.
     """
 
     def __init__(self, *, cooldown_duration: float):
@@ -99,7 +99,7 @@ class _CommandCooldownManager:
                 cooldowns_list.append(_CooldownItem(call_arguments, timeout_timestamp))
 
     def is_on_cooldown(self, channel: Hashable, call_arguments: _ArgsTuple) -> bool:
-        """Check whether ``call_arguments`` is on cooldown in ``channel``."""
+        """Check whether `call_arguments` is on cooldown in `channel`."""
         current_time = time.monotonic()
         try:
             return self._cooldowns.get((channel, call_arguments), -math.inf) > current_time
@@ -115,9 +115,9 @@ class _CommandCooldownManager:
 
     async def _periodical_cleanup(self, initial_delay: float) -> None:
         """
-        Wait for `initial_delay`, after that delete stale items every hour.
+        Delete stale items every hour after waiting for `initial_delay`.
 
-        The `initial_delay` ensures we're not running cleanups for every command at the same time.
+        The `initial_delay` ensures cleanups are not running for every command at the same time.
         """
         await asyncio.sleep(initial_delay)
         while True:
@@ -151,7 +151,7 @@ def block_duplicate_invocations(
 
     Args:
         cooldown_duration: Length of the cooldown in seconds.
-        send_notice: If True, the user is notified of the cooldown with a reply.
+        send_notice: If :obj:`True`, notify the user about the cooldown with a reply.
 
     Returns:
         A decorator that adds a wrapper which applies the cooldowns.
diff --git a/botcore/utils/function.py b/botcore/utils/function.py
index 1cde5cd9..e8d24e90 100644
--- a/botcore/utils/function.py
+++ b/botcore/utils/function.py
@@ -28,17 +28,14 @@ def update_wrapper_globals(
     ignored_conflict_names: Set[str] = frozenset(),
 ) -> Callable[_P, _R]:
     r"""
-    Update globals of the ``wrapper`` function with the globals from the ``wrapped`` function.
+    Create a copy of ``wrapper``\, the copy's globals are updated with ``wrapped``\'s globals.
 
     For forwardrefs in command annotations, discord.py uses the ``__global__`` attribute of the function
-    to resolve their values, with decorators that replace the function this breaks because they have
+    to resolve their values. This breaks for decorators that replace the function because they have
     their own globals.
 
-    This function creates a new function functionally identical to ``wrapper``\, which has the globals replaced with
-    a merge of ``wrapped``\s globals and the ``wrapper``\s globals.
-
     .. warning::
-        This function captures the state of ``wrapped``\'s module's globals when it's called,
+        This function captures the state of ``wrapped``\'s module's globals when it's called;
         changes won't be reflected in the new function's globals.
 
     Args:
diff --git a/docs/utils.py b/docs/utils.py
index a4662ba4..9d299ebf 100644
--- a/docs/utils.py
+++ b/docs/utils.py
@@ -107,7 +107,7 @@ def _global_assign_pos(ast_: NodeWithBody, name: str) -> typing.Union[tuple[int,
     """
     Find the first instance where the `name` global is defined in `ast_`.
 
-    Top level assignments, and assignments nested in top level ifs are checked.
+    Check top-level assignments and assignments nested in top-level if blocks.
     """
     for ast_obj in ast_.body:
         if isinstance(ast_obj, ast.Assign):