Document hook errors

arc/utils/hooks/basic.py

@@ -25,6 +25,11 @@ def guild_only(ctx: Context[t.Any]) -> HookResult:
     ```py
     @arc.with_hook(arc.guild_only)
     ```
+
+    Raises
+    ------
+    GuildOnlyError
+        If the command is invoked outside of a guild.
     """
     if ctx.guild_id is None:
         raise GuildOnlyError("This command can only be used in a guild.")
@@ -39,6 +44,11 @@ def dm_only(ctx: Context[t.Any]) -> HookResult:
     ```py
     @arc.with_hook(arc.dm_only)
     ```
+
+    Raises
+    ------
+    DMOnlyError
+        If the command is invoked outside of a DM.
     """
     if ctx.guild_id is not None:
         raise DMOnlyError("This command can only be used in a DM.")
@@ -53,6 +63,11 @@ def owner_only(ctx: Context[t.Any]) -> HookResult:
     ```py
     @arc.with_hook(arc.owner_only)
     ```
+
+    Raises
+    ------
+    NotOwnerError
+        If the command is invoked by a non-owner.
     """
     if ctx.author.id not in ctx.client.owner_ids:
         raise NotOwnerError("This command can only be used by the application owners.")
@@ -83,6 +98,13 @@ def has_permissions(perms: hikari.Permissions) -> t.Callable[[Context[t.Any]], H
     perms : hikari.Permissions
         The permissions to check for.
 
+    Raises
+    ------
+    GuildOnlyError
+        If the command is invoked outside of a guild.
+    InvokerMissingPermissionsError
+        If the invoker is missing some of the specified permissions.
+
     Examples
     --------
     ```py
@@ -120,6 +142,13 @@ def bot_has_permissions(perms: hikari.Permissions) -> t.Callable[[Context[t.Any]
     perms : hikari.Permissions
         The permissions to check for.
 
+    Raises
+    ------
+    GuildOnlyError
+        If the command is invoked outside of a guild.
+    BotMissingPermissionsError
+        If the bot is missing some of the specified permissions.
+
     Examples
     --------
     ```py

arc/utils/hooks/limiters.py

@@ -77,6 +77,11 @@ def global_limiter(period: float, limit: int) -> LimiterHook[t.Any]:
     limit : int
         The amount of requests allowed in a bucket.
 
+    Raises
+    ------
+    RateLimiterExhaustedError
+        If the limiter is exhausted.
+
     Examples
     --------
     ```py
@@ -98,6 +103,11 @@ def guild_limiter(period: float, limit: int) -> LimiterHook[t.Any]:
     limit : int
         The amount of requests allowed in a bucket.
 
+    Raises
+    ------
+    RateLimiterExhaustedError
+        If the limiter is exhausted.
+
     Examples
     --------
     ```py
@@ -119,6 +129,11 @@ def channel_limiter(period: float, limit: int) -> LimiterHook[t.Any]:
     limit : int
         The amount of requests allowed in a bucket.
 
+    Raises
+    ------
+    RateLimiterExhaustedError
+        If the limiter is exhausted.
+
     Examples
     --------
     ```py
@@ -140,6 +155,11 @@ def user_limiter(period: float, limit: int) -> LimiterHook[t.Any]:
     limit : int
         The amount of requests allowed in a bucket.
 
+    Raises
+    ------
+    RateLimiterExhaustedError
+        If the limiter is exhausted.
+
     Examples
     --------
     ```py
@@ -162,6 +182,11 @@ def member_limiter(period: float, limit: int) -> LimiterHook[t.Any]:
     limit : int
         The amount of requests allowed in a bucket.
 
+    Raises
+    ------
+    RateLimiterExhaustedError
+        If the limiter is exhausted.
+
     Examples
     --------
     ```py
@@ -185,6 +210,11 @@ def custom_limiter(period: float, limit: int, get_key_with: t.Callable[[Context[
         For instance, to create a ratelimiter that is shared across all contexts in a guild,
         you would use `lambda ctx: str(ctx.guild_id)`.
 
+    Raises
+    ------
+    RateLimiterExhaustedError
+        If the limiter is exhausted.
+
     Examples
     --------
     ```py