Improve documentation

8 files changed, 45 insertions, 40 deletions

diff --git a/discord/ext/commands/bot.py b/discord/ext/commands/bot.py
index 80511d23..66e245dc 100644
--- a/discord/ext/commands/bot.py
+++ b/discord/ext/commands/bot.py
@@ -147,7 +147,7 @@ class BotBase(GroupMixin):
 
         The default command error handler provided by the bot.
 
-        By default this prints to ``sys.stderr`` however it could be
+        By default this prints to :data:`sys.stderr` however it could be
         overridden to have a different implementation.
 
         This only fires if you do not specify any listeners for command error.
@@ -208,7 +208,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:
@@ -241,7 +241,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
@@ -288,6 +288,11 @@ class BotBase(GroupMixin):
         -----------
         user: :class:`.abc.User`
             The user to check for.
+
+        Returns
+        --------
+        :class:`bool`
+            Whether the user is the owner.
         """
 
         if self.owner_id is None:
@@ -314,7 +319,7 @@ class BotBase(GroupMixin):
 
         Parameters
         -----------
-        coro
+        coro: :ref:`coroutine <coroutine>`
             The coroutine to register as the pre-invoke hook.
 
         Raises
@@ -347,7 +352,7 @@ class BotBase(GroupMixin):
 
         Parameters
         -----------
-        coro
+        coro: :ref:`coroutine <coroutine>`
             The coroutine to register as the post-invoke hook.
 
         Raises
@@ -420,7 +425,7 @@ class BotBase(GroupMixin):
         event listener. Basically this allows you to listen to multiple
         events from different places e.g. such as :func:`.on_ready`
 
-        The functions being listened to must be a coroutine.
+        The functions being listened to must be a :ref:`coroutine <coroutine>`.
 
         Example
         --------
diff --git a/discord/ext/commands/cog.py b/discord/ext/commands/cog.py
index 66988a02..9f3c745c 100644
--- a/discord/ext/commands/cog.py
+++ b/discord/ext/commands/cog.py
@@ -34,7 +34,7 @@ __all__ = (
 )
 
 class CogMeta(type):
-    """A　metaclass for defining a cog.
+    """A metaclass for defining a cog.
 
     Note that you should probably not use this directly. It is exposed
     purely for documentation purposes along with making custom metaclasses to intermix
diff --git a/discord/ext/commands/context.py b/discord/ext/commands/context.py
index 9429fd8e..fb9dcfc2 100644
--- a/discord/ext/commands/context.py
+++ b/discord/ext/commands/context.py
@@ -34,7 +34,7 @@ class Context(discord.abc.Messageable):
     the invocation context. This class is not created manually and is instead
     passed around to commands as the first parameter.
 
-    This class implements the :class:`abc.Messageable` ABC.
+    This class implements the :class:`~discord.abc.Messageable` ABC.
 
     Attributes
     -----------
@@ -61,12 +61,12 @@ class Context(discord.abc.Messageable):
     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`.
+        ``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
         nonsense string. If nothing was passed to attempt a call to a
-        subcommand then this is set to `None`.
+        subcommand then this is set to ``None``.
     command_failed: :class:`bool`
         A boolean that indicates if the command failed to be parsed, checked,
         or invoked.
diff --git a/discord/ext/commands/converter.py b/discord/ext/commands/converter.py
index 12b4fd60..86a3db45 100644
--- a/discord/ext/commands/converter.py
+++ b/discord/ext/commands/converter.py
@@ -66,7 +66,7 @@ class Converter:
     special cased ``discord`` classes.
 
     Classes that derive from this should override the :meth:`~.Converter.convert`
-    method to do its conversion logic. This method must be a coroutine.
+    method to do its conversion logic. This method must be a :ref:`coroutine <coroutine>`.
     """
 
     async def convert(self, ctx, argument):
@@ -96,7 +96,7 @@ class IDConverter(Converter):
         return self._id_regex.match(argument)
 
 class MemberConverter(IDConverter):
-    """Converts to a :class:`Member`.
+    """Converts to a :class:`~discord.Member`.
 
     All lookups are via the local guild. If in a DM context, then the lookup
     is done by the global cache.
@@ -134,7 +134,7 @@ class MemberConverter(IDConverter):
         return result
 
 class UserConverter(IDConverter):
-    """Converts to a :class:`User`.
+    """Converts to a :class:`~discord.User`.
 
     All lookups are via the global user cache.
 
@@ -210,7 +210,7 @@ class MessageConverter(Converter):
             raise BadArgument("Can't read messages in {channel}".format(channel=channel.mention))
 
 class TextChannelConverter(IDConverter):
-    """Converts to a :class:`TextChannel`.
+    """Converts to a :class:`~discord.TextChannel`.
 
     All lookups are via the local guild. If in a DM context, then the lookup
     is done by the global cache.
@@ -249,7 +249,7 @@ class TextChannelConverter(IDConverter):
         return result
 
 class VoiceChannelConverter(IDConverter):
-    """Converts to a :class:`VoiceChannel`.
+    """Converts to a :class:`~discord.VoiceChannel`.
 
     All lookups are via the local guild. If in a DM context, then the lookup
     is done by the global cache.
@@ -287,7 +287,7 @@ class VoiceChannelConverter(IDConverter):
         return result
 
 class CategoryChannelConverter(IDConverter):
-    """Converts to a :class:`CategoryChannel`.
+    """Converts to a :class:`~discord.CategoryChannel`.
 
     All lookups are via the local guild. If in a DM context, then the lookup
     is done by the global cache.
@@ -326,7 +326,7 @@ class CategoryChannelConverter(IDConverter):
         return result
 
 class ColourConverter(Converter):
-    """Converts to a :class:`Colour`.
+    """Converts to a :class:`~discord.Colour`.
 
     The following formats are accepted:
 
@@ -355,7 +355,7 @@ class ColourConverter(Converter):
             return method()
 
 class RoleConverter(IDConverter):
-    """Converts to a :class:`Role`.
+    """Converts to a :class:`~discord.Role`.
 
     All lookups are via the local guild. If in a DM context, then the lookup
     is done by the global cache.
@@ -382,12 +382,12 @@ class RoleConverter(IDConverter):
         return result
 
 class GameConverter(Converter):
-    """Converts to :class:`Game`."""
+    """Converts to :class:`~discord.Game`."""
     async def convert(self, ctx, argument):
         return discord.Game(name=argument)
 
 class InviteConverter(Converter):
-    """Converts to a :class:`Invite`.
+    """Converts to a :class:`~discord.Invite`.
 
     This is done via an HTTP request using :meth:`.Bot.fetch_invite`.
     """
@@ -399,7 +399,7 @@ class InviteConverter(Converter):
             raise BadArgument('Invite is invalid or expired') from exc
 
 class EmojiConverter(IDConverter):
-    """Converts to a :class:`Emoji`.
+    """Converts to a :class:`~discord.Emoji`.
 
     All lookups are done for the local guild first, if available. If that lookup
     fails, then it checks the client's global cache.
@@ -439,7 +439,7 @@ class EmojiConverter(IDConverter):
         return result
 
 class PartialEmojiConverter(Converter):
-    """Converts to a :class:`PartialEmoji`.
+    """Converts to a :class:`~discord.PartialEmoji`.
 
     This is done by extracting the animated flag, name and ID from the emoji.
     """
@@ -460,7 +460,7 @@ class clean_content(Converter):
     """Converts the argument to mention scrubbed version of
     said content.
 
-    This behaves similarly to :attr:`.Message.clean_content`.
+    This behaves similarly to :attr:`~discord.Message.clean_content`.
 
     Attributes
     ------------
diff --git a/discord/ext/commands/core.py b/discord/ext/commands/core.py
index a4ab3dce..f951ab8e 100644
--- a/discord/ext/commands/core.py
+++ b/discord/ext/commands/core.py
@@ -145,10 +145,10 @@ class Command(_BaseCommand):
         If the command is invoked while it is disabled, then
         :exc:`.DisabledCommand` is raised to the :func:`.on_command_error`
         event. Defaults to ``True``.
-    parent: Optional[command]
+    parent: Optional[:class:`Command`]
         The parent command that this command belongs to. ``None`` if there
         isn't one.
-    checks
+    checks: List[Callable[..., :class:`bool`]]
         A list of predicates that verifies if the command could be executed
         with the given :class:`.Context` as the sole parameter. If an exception
         is necessary to be thrown to signal failure, then one inherited from
@@ -297,7 +297,7 @@ class Command(_BaseCommand):
         return other
 
     def copy(self):
-        """Creates a copy of this :class:`Command`."""
+        """Creates a copy of this command."""
         ret = self.__class__(self.callback, **self.__original_kwargs__)
         return self._ensure_assignment_on_copy(ret)
 
@@ -505,7 +505,7 @@ class Command(_BaseCommand):
 
     @property
     def full_parent_name(self):
-        """Retrieves the fully qualified parent command name.
+        """:class:`str`: Retrieves the fully qualified parent command name.
 
         This the base command name required to execute it. For example,
         in ``?one two three`` the parent name would be ``one two``.
@@ -520,7 +520,7 @@ class Command(_BaseCommand):
 
     @property
     def parents(self):
-        """Retrieves the parents of this command.
+        """:class:`Command`: Retrieves the parents of this command.
 
         If the command has no parents then it returns an empty :class:`list`.
 
@@ -550,7 +550,7 @@ class Command(_BaseCommand):
 
     @property
     def qualified_name(self):
-        """Retrieves the fully qualified command name.
+        """:class:`str`: Retrieves the fully qualified command name.
 
         This is the full parent name with the command name as well.
         For example, in ``?one two three`` the qualified name would be
@@ -688,7 +688,7 @@ class Command(_BaseCommand):
 
         Parameters
         -----------
-        ctx: :class:`.Context.`
+        ctx: :class:`.Context`
             The invocation context to use when checking the commands cooldown status.
 
         Returns
@@ -821,12 +821,12 @@ class Command(_BaseCommand):
 
     @property
     def cog_name(self):
-        """The name of the cog this command belongs to. None otherwise."""
+        """:class:`str`: The name of the cog this command belongs to. None otherwise."""
         return type(self.cog).__cog_name__ if self.cog is not None else None
 
     @property
     def short_doc(self):
-        """Gets the "short" documentation of a command.
+        """:class:`str`: Gets the "short" documentation of a command.
 
         By default, this is the :attr:`brief` attribute.
         If that lookup leads to an empty string then the first line of the
@@ -851,7 +851,7 @@ class Command(_BaseCommand):
 
     @property
     def signature(self):
-        """Returns a POSIX-like signature useful for help command output."""
+        """:class:`str`: Returns a POSIX-like signature useful for help command output."""
         if self.usage is not None:
             return self.usage
 
@@ -971,7 +971,7 @@ class GroupMixin:
 
         Parameters
         -----------
-        command
+        command: :class:`Command`
             The command to add.
 
         Raises
@@ -1107,7 +1107,7 @@ class Group(GroupMixin, Command):
 
     Attributes
     -----------
-    invoke_without_command: :class:`bool`
+    invoke_without_command: Optional[: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
@@ -1116,7 +1116,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: :class:`bool`
+    case_insensitive: Optional[:class:`bool`]
         Indicates if the group's commands should be case insensitive.
         Defaults to ``False``.
     """
@@ -1301,7 +1301,7 @@ def check(predicate):
 
     Parameters
     -----------
-    predicate: Callable[:class:`Context`, :class:`bool`]
+    predicate: Callable[[:class:`Context`], :class:`bool`]
         The predicate to check if the command should be invoked.
     """
 
diff --git a/discord/ext/commands/errors.py b/discord/ext/commands/errors.py
index 85a45297..fdbd9033 100644
--- a/discord/ext/commands/errors.py
+++ b/discord/ext/commands/errors.py
@@ -374,7 +374,7 @@ class BotMissingPermissions(CheckFailure):
         super().__init__(message, *args)
 
 class BadUnionArgument(UserInputError):
-    """Exception raised when a :class:`typing.Union` converter fails for all
+    """Exception raised when a :data:`typing.Union` converter fails for all
     its associated types.
 
     This inherits from :exc:`UserInputError`
diff --git a/discord/ext/commands/help.py b/discord/ext/commands/help.py
index 332f4aff..0c36c14f 100644
--- a/discord/ext/commands/help.py
+++ b/discord/ext/commands/help.py
@@ -550,7 +550,7 @@ class HelpCommand:
         return max(as_lengths, default=0)
 
     def get_destination(self):
-        """Returns the :class:`abc.Messageable` where the help command will be output.
+        """Returns the :class:`~discord.abc.Messageable` where the help command will be output.
 
         You can override this method to customise the behaviour.
 
diff --git a/discord/ext/tasks/__init__.py b/discord/ext/tasks/__init__.py
index b53539eb..9ea0b1ac 100644
--- a/discord/ext/tasks/__init__.py
+++ b/discord/ext/tasks/__init__.py
@@ -245,7 +245,7 @@ class Loop:
         return self._task
 
     def is_being_cancelled(self):
-        """:class:`bool`: Whether the task is being cancelled."""
+        """Whether the task is being cancelled."""
         return self._is_being_cancelled
 
     def failed(self):