[V3 Docs] Docs for utils package (#1085)

* Docstrings for chat formatting

* Docstrings for mod utils

* Type checking

* Override CSS to highlight object name in definition

* More typing

* Utils docs pages

* Fix typo here

redbot/core/utils/mod.py

@@ -1,5 +1,6 @@
 import asyncio
-from typing import List
+from datetime import timedelta
+from typing import List, Iterable, Union
 
 import discord
 
@@ -9,6 +10,32 @@ from redbot.core.bot import Red
 
 async def mass_purge(messages: List[discord.Message],
                      channel: discord.TextChannel):
+    """Bulk delete messages from a channel.
+
+    If more than 100 messages are supplied, the bot will delete 100 messages at
+    a time, sleeping between each action.
+
+    Note
+    ----
+    Messages must not be older than 14 days, and the bot must not be a user
+    account.
+
+    Parameters
+    ----------
+    messages : `list` of `discord.Message`
+        The messages to bulk delete.
+    channel : discord.TextChannel
+        The channel to delete messages from.
+
+    Raises
+    ------
+    discord.Forbidden
+        You do not have proper permissions to delete the messages or you’re not
+        using a bot account.
+    discord.HTTPException
+        Deleting the messages failed.
+
+    """
     while messages:
         if len(messages) > 1:
             await channel.delete_messages(messages[:100])
@@ -19,7 +46,17 @@ async def mass_purge(messages: List[discord.Message],
         await asyncio.sleep(1.5)
 
 
-async def slow_deletion(messages: List[discord.Message]):
+async def slow_deletion(messages: Iterable[discord.Message]):
+    """Delete a list of messages one at a time.
+
+    Any exceptions raised when trying to delete the message will be silenced.
+
+    Parameters
+    ----------
+    messages : `iterable` of `discord.Message`
+        The messages to delete.
+
+    """
     for message in messages:
         try:
             await message.delete()
@@ -28,23 +65,62 @@ async def slow_deletion(messages: List[discord.Message]):
 
 
 def get_audit_reason(author: discord.Member, reason: str = None):
-    """Helper function to construct a reason to be provided
-    as the reason to appear in the audit log."""
+    """Construct a reason to appear in the audit log.
+
+    Parameters
+    ----------
+    author : discord.Member
+        The author behind the audit log action.
+    reason : str
+        The reason behidn the audit log action.
+
+    Returns
+    -------
+    str
+        The formatted audit log reason.
+
+    """
     return \
         "Action requested by {} (ID {}). Reason: {}".format(author, author.id, reason) if reason else \
         "Action requested by {} (ID {}).".format(author, author.id)
 
 
-async def is_allowed_by_hierarchy(
-        bot: Red, settings: Config, server: discord.Guild,
-        mod: discord.Member, user: discord.Member):
-    if not await settings.guild(server).respect_hierarchy():
+async def is_allowed_by_hierarchy(bot: Red,
+                                  settings: Config,
+                                  guild: discord.Guild,
+                                  mod: discord.Member,
+                                  user: discord.Member):
+    if not await settings.guild(guild).respect_hierarchy():
         return True
-    is_special = mod == server.owner or await bot.is_owner(mod)
+    is_special = mod == guild.owner or await bot.is_owner(mod)
     return mod.top_role.position > user.top_role.position or is_special
 
 
-async def is_mod_or_superior(bot: Red, obj: discord.Message or discord.Member or discord.Role):
+async def is_mod_or_superior(
+    bot: Red, obj: Union[discord.Message, discord.Member, discord.Role]):
+    """Check if an object has mod or superior permissions.
+
+    If a message is passed, its author's permissions are checked. If a role is
+    passed, it simply checks if it is one of either the admin or mod roles.
+
+    Parameters
+    ----------
+    bot : redbot.core.bot.Red
+        The bot object.
+    obj : `discord.Message` or `discord.Member` or `discord.Role`
+        The object to check permissions for.
+
+    Returns
+    -------
+    bool
+        :code:`True` if the object has mod permissions.
+
+    Raises
+    ------
+    TypeError
+        If the wrong type of ``obj`` was passed.
+
+    """
     user = None
     if isinstance(obj, discord.Message):
         user = obj.author
@@ -76,7 +152,20 @@ async def is_mod_or_superior(bot: Red, obj: discord.Message or discord.Member or
         return False
 
 
-def strfdelta(delta):
+def strfdelta(delta: timedelta):
+    """Format a timedelta object to a message with time units.
+
+    Parameters
+    ----------
+    delta : datetime.timedelta
+        The duration to parse.
+
+    Returns
+    -------
+    str
+        A message representing the timedelta with units.
+
+    """
     s = []
     if delta.days:
         ds = '%i day' % delta.days
@@ -97,7 +186,31 @@ def strfdelta(delta):
     return ' '.join(s)
 
 
-async def is_admin_or_superior(bot: Red, obj: discord.Message or discord.Role or discord.Member):
+async def is_admin_or_superior(
+    bot: Red, obj: Union[discord.Message, discord.Member, discord.Role]):
+    """Same as `is_mod_or_superior` except for admin permissions.
+
+    If a message is passed, its author's permissions are checked. If a role is
+    passed, it simply checks if it is the admin role.
+
+    Parameters
+    ----------
+    bot : redbot.core.bot.Red
+        The bot object.
+    obj : `discord.Message` or `discord.Member` or `discord.Role`
+        The object to check permissions for.
+
+    Returns
+    -------
+    bool
+        :code:`True` if the object has admin permissions.
+
+    Raises
+    ------
+    TypeError
+        If the wrong type of ``obj`` was passed.
+
+    """
     user = None
     if isinstance(obj, discord.Message):
         user = obj.author