Fix various inconsistencies within the documentation (#5067)

6 files changed, 76 insertions, 47 deletions

diff --git a/discord/ext/commands/bot.py b/discord/ext/commands/bot.py
index 8485c4ab..724ab7cb 100644
--- a/discord/ext/commands/bot.py
+++ b/discord/ext/commands/bot.py
@@ -215,7 +215,7 @@ class BotBase(GroupMixin):
             The function that was used as a global check.
         call_once: :class:`bool`
             If the function should only be called once per
-            :meth:`Command.invoke` call.
+            :meth:`.Command.invoke` call.
         """
 
         if call_once:
@@ -248,7 +248,7 @@ class BotBase(GroupMixin):
         r"""A decorator that adds a "call once" global check to the bot.
 
         Unlike regular global checks, this one is called only once
-        per :meth:`Command.invoke` call.
+        per :meth:`.Command.invoke` call.
 
         Regular global checks are called whenever a command is called
         or :meth:`.Command.can_run` is called. This type of check
@@ -513,6 +513,11 @@ class BotBase(GroupMixin):
             The name of the cog you are requesting.
             This is equivalent to the name passed via keyword
             argument in class creation or the class name if unspecified.
+
+        Returns
+        --------
+        Optional[:class:`Cog`]
+            The cog that was requested. If not found, returns ``None``.
         """
         return self.__cogs.get(name)
 
@@ -991,11 +996,11 @@ class Bot(BotBase, discord.Client):
         :meth:`.is_owner` then it is fetched automatically using
         :meth:`~.Bot.application_info`.
     owner_ids: Optional[Collection[:class:`int`]]
-        The user IDs that owns the bot. This is similar to `owner_id`.
+        The user IDs that owns the bot. This is similar to :attr:`owner_id`.
         If this is not set and the application is team based, then it is
         fetched automatically using :meth:`~.Bot.application_info`.
         For performance reasons it is recommended to use a :class:`set`
-        for the collection. You cannot set both `owner_id` and `owner_ids`.
+        for the collection. You cannot set both ``owner_id`` and ``owner_ids``.
 
         .. versionadded:: 1.3
     """
diff --git a/discord/ext/commands/cog.py b/discord/ext/commands/cog.py
index 5c81e4a5..b8e25917 100644
--- a/discord/ext/commands/cog.py
+++ b/discord/ext/commands/cog.py
@@ -72,7 +72,7 @@ class CogMeta(type):
         The cog name. By default, it is the name of the class with no modification.
     command_attrs: :class:`dict`
         A list of attributes to apply to every command inside this cog. The dictionary
-        is passed into the :class:`Command` (or its subclass) options at ``__init__``.
+        is passed into the :class:`Command` options at ``__init__``.
         If you specify attributes inside the command attribute in the class, it will
         override the one specified inside this attribute. For example:
 
@@ -188,12 +188,16 @@ class Cog(metaclass=CogMeta):
         return self
 
     def get_commands(self):
-        r"""Returns a :class:`list` of :class:`.Command`\s that are
-        defined inside this cog.
+        r"""
+        Returns
+        --------
+        List[:class:`.Command`]
+            A :class:`list` of :class:`.Command`\s that are
+            defined inside this cog.
 
-        .. note::
+            .. note::
 
-            This does not include subcommands.
+                This does not include subcommands.
         """
         return [c for c in self.__cog_commands__ if c.parent is None]
 
@@ -221,7 +225,13 @@ class Cog(metaclass=CogMeta):
                     yield from command.walk_commands()
 
     def get_listeners(self):
-        """Returns a :class:`list` of (name, function) listener pairs that are defined in this cog."""
+        """Returns a :class:`list` of (name, function) listener pairs that are defined in this cog.
+
+        Returns
+        --------
+        List[Tuple[:class:`str`, :ref:`coroutine <coroutine>`]]
+            The listeners defined in this cog.
+        """
         return [(name, getattr(self, method_name)) for name, method_name in self.__cog_listeners__]
 
     @classmethod
diff --git a/discord/ext/commands/context.py b/discord/ext/commands/context.py
index 5635cb42..bb48935c 100644
--- a/discord/ext/commands/context.py
+++ b/discord/ext/commands/context.py
@@ -52,16 +52,14 @@ class Context(discord.abc.Messageable):
         :func:`on_command_error` event then this dict could be incomplete.
     prefix: :class:`str`
         The prefix that was used to invoke the command.
-    command
-        The command (i.e. :class:`.Command` or its subclasses) that is being
-        invoked currently.
+    command: :class:`Command`
+        The command that is being invoked currently.
     invoked_with: :class:`str`
         The command name that triggered this invocation. Useful for finding out
         which alias called the command.
-    invoked_subcommand
-        The subcommand (i.e. :class:`.Command` or its subclasses) that was
-        invoked. If no valid subcommand was invoked then this is equal to
-        ``None``.
+    invoked_subcommand: :class:`Command`
+        The subcommand that was invoked.
+        If no valid subcommand was invoked then this is equal to ``None``.
     subcommand_passed: Optional[:class:`str`]
         The string that was attempted to call a subcommand. This does not have
         to point to a valid registered subcommand and could just point to a
@@ -110,7 +108,7 @@ class Context(discord.abc.Messageable):
         Parameters
         -----------
         command: :class:`.Command`
-            A command or subclass of a command that is going to be called.
+            The command that is going to be called.
         \*args
             The arguments to to use.
         \*\*kwargs
@@ -188,7 +186,7 @@ class Context(discord.abc.Messageable):
 
     @property
     def valid(self):
-        """Checks if the invocation context is valid to be invoked with."""
+        """:class:`bool`: Checks if the invocation context is valid to be invoked with."""
         return self.prefix is not None and self.command is not None
 
     async def _get_channel(self):
@@ -196,7 +194,7 @@ class Context(discord.abc.Messageable):
 
     @property
     def cog(self):
-        """Returns the cog associated with this context's command. None if it does not exist."""
+        """:class:`.Cog`: Returns the cog associated with this context's command. None if it does not exist."""
 
         if self.command is None:
             return None
@@ -204,22 +202,28 @@ class Context(discord.abc.Messageable):
 
     @discord.utils.cached_property
     def guild(self):
-        """Returns the guild associated with this context's command. None if not available."""
+        """Optional[:class:`.Guild`]: Returns the guild associated with this context's command. None if not available."""
         return self.message.guild
 
     @discord.utils.cached_property
     def channel(self):
-        """Returns the channel associated with this context's command. Shorthand for :attr:`.Message.channel`."""
+        """:class:`.TextChannel`:
+        Returns the channel associated with this context's command. Shorthand for :attr:`.Message.channel`.
+        """
         return self.message.channel
 
     @discord.utils.cached_property
     def author(self):
-        """Returns the author associated with this context's command. Shorthand for :attr:`.Message.author`"""
+        """Union[:class:`~discord.User`, :class:`.Member`]:
+        Returns the author associated with this context's command. Shorthand for :attr:`.Message.author`
+        """
         return self.message.author
 
     @discord.utils.cached_property
     def me(self):
-        """Similar to :attr:`.Guild.me` except it may return the :class:`.ClientUser` in private message contexts."""
+        """Union[:class:`.Member`, :class:`.ClientUser`]:
+        Similar to :attr:`.Guild.me` except it may return the :class:`.ClientUser` in private message contexts.
+        """
         return self.guild.me if self.guild is not None else self.bot.user
 
     @property
diff --git a/discord/ext/commands/core.py b/discord/ext/commands/core.py
index 9534f527..7bfe6196 100644
--- a/discord/ext/commands/core.py
+++ b/discord/ext/commands/core.py
@@ -142,12 +142,11 @@ class Command(_BaseCommand):
         The coroutine that is executed when the command is called.
     help: :class:`str`
         The long help text for the command.
-    brief: :class:`str`
-        The short help text for the command. If this is not specified
-        then the first line of the long help text is used instead.
+    brief: Optional[:class:`str`]
+        The short help text for the command.
     usage: :class:`str`
         A replacement for arguments in the default help text.
-    aliases: Union[:class:`list`, :class:`tuple`]
+    aliases: Union[List[:class:`str`], Tuple[:class:`str`]]
         The list of aliases the command can be invoked under.
     enabled: :class:`bool`
         A boolean that indicates if the command is currently enabled.
@@ -384,7 +383,13 @@ class Command(_BaseCommand):
         return other
 
     def copy(self):
-        """Creates a copy of this command."""
+        """Creates a copy of this command.
+
+        Returns
+        --------
+        :class:`Command`
+            A new instance of this command.
+        """
         ret = self.__class__(self.callback, **self.__original_kwargs__)
         return self._ensure_assignment_on_copy(ret)
 
@@ -574,7 +579,8 @@ class Command(_BaseCommand):
 
     @property
     def clean_params(self):
-        """Retrieves the parameter OrderedDict without the context or self parameters.
+        """OrderedDict[:class:`str`, :class:`inspect.Parameter`]:
+        Retrieves the parameter OrderedDict without the context or self parameters.
 
         Useful for inspecting signature.
         """
@@ -608,7 +614,7 @@ class Command(_BaseCommand):
 
     @property
     def parents(self):
-        """:class:`Command`: Retrieves the parents of this command.
+        """List[:class:`Command`]: Retrieves the parents of this command.
 
         If the command has no parents then it returns an empty :class:`list`.
 
@@ -626,7 +632,7 @@ class Command(_BaseCommand):
 
     @property
     def root_parent(self):
-        """Retrieves the root parent of this command.
+        """Optional[:class:`Command`]: Retrieves the root parent of this command.
 
         If the command has no parents then it returns ``None``.
 
@@ -920,7 +926,7 @@ class Command(_BaseCommand):
 
     @property
     def cog_name(self):
-        """:class:`str`: The name of the cog this command belongs to. None otherwise."""
+        """Optional[:class:`str`]: The name of the cog this command belongs to, if any."""
         return type(self.cog).__cog_name__ if self.cog is not None else None
 
     @property
@@ -1046,7 +1052,7 @@ class GroupMixin:
     Attributes
     -----------
     all_commands: :class:`dict`
-        A mapping of command name to :class:`.Command` or subclass
+        A mapping of command name to :class:`.Command`
         objects.
     case_insensitive: :class:`bool`
         Whether the commands should be case insensitive. Defaults to ``False``.
@@ -1069,8 +1075,7 @@ class GroupMixin:
             self.remove_command(command.name)
 
     def add_command(self, command):
-        """Adds a :class:`.Command` or its subclasses into the internal list
-        of commands.
+        """Adds a :class:`.Command` into the internal list of commands.
 
         This is usually not called, instead the :meth:`~.GroupMixin.command` or
         :meth:`~.GroupMixin.group` shortcut decorators are used instead.
@@ -1104,7 +1109,7 @@ class GroupMixin:
             self.all_commands[alias] = command
 
     def remove_command(self, name):
-        """Remove a :class:`.Command` or subclasses from the internal list
+        """Remove a :class:`.Command` from the internal list
         of commands.
 
         This could also be used as a way to remove aliases.
@@ -1116,9 +1121,9 @@ class GroupMixin:
 
         Returns
         --------
-        :class:`.Command` or subclass
+        Optional[:class:`.Command`]
             The command that was removed. If the name is not valid then
-            `None` is returned instead.
+            ``None`` is returned instead.
         """
         command = self.all_commands.pop(name, None)
 
@@ -1147,7 +1152,7 @@ class GroupMixin:
                 yield from command.walk_commands()
 
     def get_command(self, name):
-        """Get a :class:`.Command` or subclasses from the internal list
+        """Get a :class:`.Command` from the internal list
         of commands.
 
         This could also be used as a way to get aliases.
@@ -1163,7 +1168,7 @@ class GroupMixin:
 
         Returns
         --------
-        :class:`Command` or subclass
+        Optional[:class:`Command`]
             The command that was requested. If not found, returns ``None``.
         """
 
@@ -1217,7 +1222,7 @@ class Group(GroupMixin, Command):
 
     Attributes
     -----------
-    invoke_without_command: Optional[:class:`bool`]
+    invoke_without_command: :class:`bool`
         Indicates if the group callback should begin parsing and
         invocation only if no subcommand was found. Useful for
         making it an error handling function to tell the user that
@@ -1226,7 +1231,7 @@ class Group(GroupMixin, Command):
         the group callback will always be invoked first. This means
         that the checks and the parsing dictated by its parameters
         will be executed. Defaults to ``False``.
-    case_insensitive: Optional[:class:`bool`]
+    case_insensitive: :class:`bool`
         Indicates if the group's commands should be case insensitive.
         Defaults to ``False``.
     """
@@ -1235,7 +1240,13 @@ class Group(GroupMixin, Command):
         super().__init__(*args, **attrs)
 
     def copy(self):
-        """Creates a copy of this :class:`Group`."""
+        """Creates a copy of this :class:`Group`.
+
+        Returns
+        --------
+        :class:`Group`
+            A new instance of this group.
+        """
         ret = super().copy()
         for cmd in self.commands:
             ret.add_command(cmd.copy())
@@ -1856,7 +1867,6 @@ def is_nsfw():
 
 def cooldown(rate, per, type=BucketType.default):
     """A decorator that adds a cooldown to a :class:`.Command`
-    or its subclasses.
 
     A cooldown allows a command to only be used a specific amount
     of times in a specific time frame. These cooldowns can be based
diff --git a/discord/ext/commands/errors.py b/discord/ext/commands/errors.py
index 23481a78..34b0b979 100644
--- a/discord/ext/commands/errors.py
+++ b/discord/ext/commands/errors.py
@@ -90,7 +90,7 @@ class ConversionError(CommandError):
     ----------
     converter: :class:`discord.ext.commands.Converter`
         The converter that failed.
-    original
+    original: :exc:`Exception`
         The original exception that was raised. You can also get this via
         the ``__cause__`` attribute.
     """
diff --git a/discord/ext/commands/help.py b/discord/ext/commands/help.py
index 226e5f6a..21a87396 100644
--- a/discord/ext/commands/help.py
+++ b/discord/ext/commands/help.py
@@ -155,7 +155,7 @@ class Paginator:
 
     @property
     def pages(self):
-        """Returns the rendered list of pages."""
+        """class:`list`: Returns the rendered list of pages."""
         # we have more than just the prefix in our current page
         if len(self._current_page) > (0 if self.prefix is None else 1):
             self.close_page()