Fix various inconsistencies within the documentation (#5067)

discord/abc.py

@@ -53,7 +53,7 @@ class Snowflake(metaclass=abc.ABCMeta):
     abstract base class.
 
     If you want to create a snowflake on your own, consider using
-    :class:`Object`.
+    :class:`.Object`.
 
     Attributes
     -----------
@@ -597,7 +597,7 @@ class GuildChannel:
         target: Union[:class:`~discord.Member`, :class:`~discord.Role`]
             The member or role to overwrite permissions for.
         overwrite: Optional[:class:`~discord.PermissionOverwrite`]
-            The permissions to allow and deny to the target, or `None` to
+            The permissions to allow and deny to the target, or ``None`` to
             delete the overwrite.
         \*\*permissions
             A keyword argument list of permissions to set for ease of use.
@@ -700,10 +700,10 @@ class GuildChannel:
         ------------
         max_age: :class:`int`
             How long the invite should last in seconds. If it's 0 then the invite
-            doesn't expire. Defaults to 0.
+            doesn't expire. Defaults to ``0``.
         max_uses: :class:`int`
             How many uses the invite could be used for. If it's 0 then there
-            are unlimited uses. Defaults to 0.
+            are unlimited uses. Defaults to ``0``.
         temporary: :class:`bool`
             Denotes that the invite grants temporary membership
             (i.e. they get kicked after they disconnect). Defaults to ``False``.

discord/activity.py

@@ -338,7 +338,7 @@ class Game(BaseActivity):
 
     @property
     def type(self):
-        """Returns the game's type. This is for compatibility with :class:`Activity`.
+        """:class:`ActivityType`: Returns the game's type. This is for compatibility with :class:`Activity`.
 
         It always returns :attr:`ActivityType.playing`.
         """
@@ -445,7 +445,7 @@ class Streaming(BaseActivity):
 
     @property
     def type(self):
-        """Returns the game's type. This is for compatibility with :class:`Activity`.
+        """:class:`ActivityType`: Returns the game's type. This is for compatibility with :class:`Activity`.
 
         It always returns :attr:`ActivityType.streaming`.
         """
@@ -530,7 +530,7 @@ class Spotify:
 
     @property
     def type(self):
-        """Returns the activity's type. This is for compatibility with :class:`Activity`.
+        """:class:`ActivityType`: Returns the activity's type. This is for compatibility with :class:`Activity`.
 
         It always returns :attr:`ActivityType.listening`.
         """
@@ -547,14 +547,14 @@ class Spotify:
 
     @property
     def colour(self):
-        """Returns the Spotify integration colour, as a :class:`Colour`.
+        """:class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`.
 
         There is an alias for this named :attr:`color`"""
         return Colour(0x1db954)
 
     @property
     def color(self):
-        """Returns the Spotify integration colour, as a :class:`Colour`.
+        """:class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`.
 
         There is an alias for this named :attr:`colour`"""
         return self.colour
@@ -697,7 +697,7 @@ class CustomActivity(BaseActivity):
 
     @property
     def type(self):
-        """Returns the activity's type. This is for compatibility with :class:`Activity`.
+        """:class:`ActivityType`: Returns the activity's type. This is for compatibility with :class:`Activity`.
 
         It always returns :attr:`ActivityType.custom`.
         """

discord/channel.py

@@ -835,6 +835,11 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
         """|coro|
 
         A shortcut method to :meth:`Guild.create_text_channel` to create a :class:`TextChannel` in the category.
+
+        Returns
+        -------
+        :class:`TextChannel`
+            The channel that was just created.
         """
         return await self.guild.create_text_channel(name, overwrites=overwrites, category=self, reason=reason, **options)
 
@@ -842,6 +847,11 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
         """|coro|
 
         A shortcut method to :meth:`Guild.create_voice_channel` to create a :class:`VoiceChannel` in the category.
+
+        Returns
+        -------
+        :class:`VoiceChannel`
+            The channel that was just created.
         """
         return await self.guild.create_voice_channel(name, overwrites=overwrites, category=self, reason=reason, **options)
 
@@ -1026,7 +1036,7 @@ class DMChannel(discord.abc.Messageable, Hashable):
 
     @property
     def created_at(self):
-        """Returns the direct message channel's creation time in UTC."""
+        """:class:`datetime.datetime`: Returns the direct message channel's creation time in UTC."""
         return utils.snowflake_time(self.id)
 
     def permissions_for(self, user=None):

discord/client.py

@@ -123,10 +123,10 @@ class Client:
     -----------
     max_messages: Optional[:class:`int`]
         The maximum number of messages to store in the internal message cache.
-        This defaults to 1000. Passing in ``None`` disables the message cache.
+        This defaults to ``1000``. Passing in ``None`` disables the message cache.
 
         .. versionchanged:: 1.3
-            Allow disabling the message cache and change the default size to 1000.
+            Allow disabling the message cache and change the default size to ``1000``.
     loop: Optional[:class:`asyncio.AbstractEventLoop`]
         The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations.
         Defaults to ``None``, in which case the default event loop is used via
@@ -138,7 +138,7 @@ class Client:
     proxy_auth: Optional[:class:`aiohttp.BasicAuth`]
         An object that represents proxy HTTP Basic Authorization.
     shard_id: Optional[:class:`int`]
-        Integer starting at 0 and less than :attr:`.shard_count`.
+        Integer starting at ``0`` and less than :attr:`.shard_count`.
     shard_count: Optional[:class:`int`]
         The total number of shards.
     fetch_offline_members: :class:`bool`
@@ -257,7 +257,7 @@ class Client:
 
     @property
     def user(self):
-        """Optional[:class:`.ClientUser`]: Represents the connected client. None if not logged in."""
+        """Optional[:class:`.ClientUser`]: Represents the connected client. ``None`` if not logged in."""
         return self._connection.user
 
     @property
@@ -654,7 +654,7 @@ class Client:
 
     @property
     def allowed_mentions(self):
-        """Optional[:class:`AllowedMentions`]: The allowed mention configuration.
+        """Optional[:class:`~discord.AllowedMentions`]: The allowed mention configuration.
 
         .. versionadded:: 1.4
         """
@@ -999,7 +999,7 @@ class Client:
             The number of guilds to retrieve.
             If ``None``, it retrieves every guild you have access to. Note, however,
             that this would make it a slow operation.
-            Defaults to 100.
+            Defaults to ``100``.
         before: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]
             Retrieves guilds before this date or object.
             If a date is provided it must be a timezone-naive datetime representing UTC time.

discord/colour.py

@@ -114,7 +114,7 @@ class Colour:
 
     @classmethod
     def default(cls):
-        """A factory method that returns a :class:`Colour` with a value of 0."""
+        """A factory method that returns a :class:`Colour` with a value of ``0``."""
         return cls(0)
 
     @classmethod

discord/embeds.py

@@ -224,7 +224,7 @@ class Embed:
 
     @property
     def footer(self):
-        """Returns an ``EmbedProxy`` denoting the footer contents.
+        """Union[:class:`EmbedProxy`, :attr:`Empty`]: Returns an ``EmbedProxy`` denoting the footer contents.
 
         See :meth:`set_footer` for possible values you can access.
 
@@ -257,7 +257,7 @@ class Embed:
 
     @property
     def image(self):
-        """Returns an ``EmbedProxy`` denoting the image contents.
+        """Union[:class:`EmbedProxy`, :attr:`Empty`]: Returns an ``EmbedProxy`` denoting the image contents.
 
         Possible attributes you can access are:
 
@@ -296,7 +296,7 @@ class Embed:
 
     @property
     def thumbnail(self):
-        """Returns an ``EmbedProxy`` denoting the thumbnail contents.
+        """Union[:class:`EmbedProxy`, :attr:`Empty`]: Returns an ``EmbedProxy`` denoting the thumbnail contents.
 
         Possible attributes you can access are:
 
@@ -335,7 +335,7 @@ class Embed:
 
     @property
     def video(self):
-        """Returns an ``EmbedProxy`` denoting the video contents.
+        """Union[:class:`EmbedProxy`, :attr:`Empty`]: Returns an ``EmbedProxy`` denoting the video contents.
 
         Possible attributes include:
 
@@ -349,7 +349,7 @@ class Embed:
 
     @property
     def provider(self):
-        """Returns an ``EmbedProxy`` denoting the provider contents.
+        """Union[:class:`EmbedProxy`, :attr:`Empty`]: Returns an ``EmbedProxy`` denoting the provider contents.
 
         The only attributes that might be accessed are ``name`` and ``url``.
 
@@ -359,7 +359,7 @@ class Embed:
 
     @property
     def author(self):
-        """Returns an ``EmbedProxy`` denoting the author contents.
+        """Union[:class:`EmbedProxy`, :attr:`Empty`]: Returns an ``EmbedProxy`` denoting the author contents.
 
         See :meth:`set_author` for possible values you can access.
 
@@ -412,7 +412,7 @@ class Embed:
 
     @property
     def fields(self):
-        """Returns a :class:`list` of ``EmbedProxy`` denoting the field contents.
+        """Union[List[:class:`EmbedProxy`], :attr:`Empty`]: Returns a :class:`list` of ``EmbedProxy`` denoting the field contents.
 
         See :meth:`add_field` for possible values you can access.
 

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
     """

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,7 +188,11 @@ class Cog(metaclass=CogMeta):
         return self
 
     def get_commands(self):
-        r"""Returns a :class:`list` of :class:`.Command`\s that are
+        r"""
+        Returns
+        --------
+        List[:class:`.Command`]
+            A :class:`list` of :class:`.Command`\s that are
             defined inside this cog.
 
             .. note::
@@ -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

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

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

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.
     """

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()

discord/file.py

@@ -31,6 +31,11 @@ class File:
     """A parameter object used for :meth:`abc.Messageable.send`
     for sending file objects.
 
+    .. note::
+
+        File objects are single use and are not meant to be reused in
+        multiple :meth:`abc.Messageable.send`\s.
+
     Attributes
     -----------
     fp: Union[:class:`str`, :class:`io.BufferedIOBase`]

discord/guild.py

@@ -362,7 +362,7 @@ class Guild(Hashable):
 
     @property
     def me(self):
-        """Similar to :attr:`Client.user` except an instance of :class:`Member`.
+        """:class:`Member`: Similar to :attr:`Client.user` except an instance of :class:`Member`.
         This is essentially used to get the member version of yourself.
         """
         self_id = self._state.user.id
@@ -370,7 +370,7 @@ class Guild(Hashable):
 
     @property
     def voice_client(self):
-        """Returns the :class:`VoiceClient` associated with this guild, if any."""
+        """Optional[:class:`VoiceClient`:] Returns the :class:`VoiceClient` associated with this guild, if any."""
         return self._state._get_voice_client(self.id)
 
     @property
@@ -526,7 +526,7 @@ class Guild(Hashable):
 
     @property
     def roles(self):
-        """Returns a :class:`list` of the guild's roles in hierarchy order.
+        """List[:class:`Role`]: Returns a :class:`list` of the guild's roles in hierarchy order.
 
         The first element of this list will be the lowest role in the
         hierarchy.
@@ -550,7 +550,7 @@ class Guild(Hashable):
 
     @property
     def default_role(self):
-        """Gets the @everyone role that all members have by default."""
+        """:class:`Role`: Gets the @everyone role that all members have by default."""
         return self.get_role(self.id)
 
     @property
@@ -695,12 +695,12 @@ class Guild(Hashable):
 
     @property
     def member_count(self):
-        """Returns the true member count regardless of it being loaded fully or not."""
+        """:class:`int`: Returns the true member count regardless of it being loaded fully or not."""
         return self._member_count
 
     @property
     def chunked(self):
-        """Returns a boolean indicating if the guild is "chunked".
+        """:class:`bool`: Returns a boolean indicating if the guild is "chunked".
 
         A chunked guild means that :attr:`member_count` is equal to the
         number of members stored in the internal :attr:`members` cache.
@@ -748,7 +748,7 @@ class Guild(Hashable):
 
         Returns
         --------
-        :class:`Member`
+        Optional[:class:`Member`]
             The member in this guild with the associated name. If not found
             then ``None`` is returned.
         """
@@ -903,6 +903,11 @@ class Guild(Hashable):
             The channel's preferred audio bitrate in bits per second.
         user_limit: :class:`int`
             The channel's limit for number of members that can be in a voice channel.
+
+        Returns
+        -------
+        :class:`VoiceChannel`
+            The channel that was just created.
         """
         data = await self._create_channel(name, overwrites, ChannelType.voice, category, reason=reason, **options)
         channel = VoiceChannel(state=self._state, guild=self, data=data)
@@ -920,6 +925,11 @@ class Guild(Hashable):
 
             The ``category`` parameter is not supported in this function since categories
             cannot have categories.
+
+        Returns
+        -------
+        :class:`CategoryChannel`
+            The channel that was just created.
         """
         data = await self._create_channel(name, overwrites, ChannelType.category, reason=reason, position=position)
         channel = CategoryChannel(state=self._state, guild=self, data=data)

discord/invite.py

@@ -163,7 +163,13 @@ class PartialInviteGuild:
         return bool(self.icon and self.icon.startswith('a_'))
 
     def icon_url_as(self, *, format=None, static_format='webp', size=1024):
-        """The same operation as :meth:`Guild.icon_url_as`."""
+        """The same operation as :meth:`Guild.icon_url_as`.
+
+        Returns
+        --------
+        :class:`Asset`
+            The resulting CDN asset.
+        """
         return Asset._from_guild_icon(self._state, self, format=format, static_format=static_format, size=size)
 
     @property
@@ -172,7 +178,13 @@ class PartialInviteGuild:
         return self.banner_url_as()
 
     def banner_url_as(self, *, format='webp', size=2048):
-        """The same operation as :meth:`Guild.banner_url_as`."""
+        """The same operation as :meth:`Guild.banner_url_as`.
+
+        Returns
+        --------
+        :class:`Asset`
+            The resulting CDN asset.
+        """
         return Asset._from_guild_image(self._state, self.id, self.banner, 'banners', format=format, size=size)
 
     @property
@@ -181,7 +193,13 @@ class PartialInviteGuild:
         return self.splash_url_as()
 
     def splash_url_as(self, *, format='webp', size=2048):
-        """The same operation as :meth:`Guild.splash_url_as`."""
+        """The same operation as :meth:`Guild.splash_url_as`.
+
+        Returns
+        --------
+        :class:`Asset`
+            The resulting CDN asset.
+        """
         return Asset._from_guild_image(self._state, self.id, self.splash, 'splashes', format=format, size=size)
 
 class Invite(Hashable):

discord/member.py

@@ -413,8 +413,13 @@ class Member(discord.abc.Messageable, _BaseUser):
 
         Parameters
         -----------
-        channel: :class:`Channel`
+        channel: :class:`abc.GuildChannel`
             The channel to check your permissions for.
+
+        Returns
+        -------
+        :class:`Permissions`
+            The resolved permissions for the member.
         """
         return channel.permissions_for(self)
 
@@ -433,7 +438,7 @@ class Member(discord.abc.Messageable, _BaseUser):
 
     @property
     def guild_permissions(self):
-        """Returns the member's guild permissions.
+        """:class:`Permissions`: Returns the member's guild permissions.
 
         This only takes into consideration the guild permissions
         and not most of the implied permissions or any of the

discord/message.py

@@ -635,7 +635,7 @@ class Message:
 
     @utils.cached_slot_property('_cs_system_content')
     def system_content(self):
-        r"""A property that returns the content that is rendered
+        r""":class:`str`: A property that returns the content that is rendered
         regardless of the :attr:`Message.type`.
 
         In the case of :attr:`MessageType.default`\, this just returns the

discord/permissions.py

@@ -86,7 +86,7 @@ class Permissions(BaseFlags):
 
     Attributes
     -----------
-    value
+    value: :class:`int`
         The raw value. This value is a bit array field of a 53-bit integer
         representing the currently available permissions. You should query
         permissions via the properties rather than using this raw value.

discord/player.py

@@ -524,7 +524,7 @@ class PCMVolumeTransformer(AudioSource):
 
     @property
     def volume(self):
-        """Retrieves or sets the volume as a floating point percentage (e.g. 1.0 for 100%)."""
+        """Retrieves or sets the volume as a floating point percentage (e.g. ``1.0`` for 100%)."""
         return self._volume
 
     @volume.setter

discord/user.py

@@ -139,7 +139,7 @@ class BaseUser(_BaseUser):
 
     @property
     def avatar_url(self):
-        """Returns an :class:`Asset` for the avatar the user has.
+        """:class:`Asset`: Returns an :class:`Asset` for the avatar the user has.
 
         If the user does not have a traditional avatar, an asset for
         the default avatar is returned instead.
@@ -717,7 +717,7 @@ class User(BaseUser, discord.abc.Messageable):
 
     @property
     def relationship(self):
-        """Returns the :class:`Relationship` with this user if applicable, ``None`` otherwise.
+        """Optional[:class:`Relationship`]: Returns the :class:`Relationship` with this user if applicable, ``None`` otherwise.
 
         .. note::
 

discord/utils.py

@@ -143,6 +143,11 @@ def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None):
         The guild to pre-select in the authorization screen, if available.
     redirect_uri: :class:`str`
         An optional valid redirect URI.
+
+    Returns
+    --------
+    :class:`str`
+        The OAuth2 URL for inviting the bot into guilds.
     """
     url = 'https://discord.com/oauth2/authorize?client_id={}&scope=bot'.format(client_id)
     if permissions is not None:
@@ -156,7 +161,16 @@ def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None):
 
 
 def snowflake_time(id):
-    """Returns the creation date in UTC of a Discord snowflake ID."""
+    """
+    Parameters
+    -----------
+    id: :class:`int`
+        The snowflake ID.
+
+    Returns
+    --------
+    :class:`datetime.datetime`
+        The creation date in UTC of a Discord snowflake ID."""
     return datetime.datetime.utcfromtimestamp(((id >> 22) + DISCORD_EPOCH) / 1000)
 
 def time_snowflake(datetime_obj, high=False):

discord/webhook.py

@@ -453,15 +453,13 @@ class Webhook:
 
     @property
     def url(self):
-        """Returns the webhook's url."""
+        """:class:`str` : Returns the webhook's url."""
         return 'https://discord.com/api/webhooks/{}/{}'.format(self.id, self.token)
 
     @classmethod
     def partial(cls, id, token, *, adapter):
         """Creates a partial :class:`Webhook`.
 
-        A partial webhook is just a webhook object with an ID and a token.
-
         Parameters
         -----------
         id: :class:`int`
@@ -472,6 +470,12 @@ class Webhook:
             The webhook adapter to use when sending requests. This is
             typically :class:`AsyncWebhookAdapter` for :doc:`aiohttp <aio:index>` or
             :class:`RequestsWebhookAdapter` for :doc:`req:index`.
+
+        Returns
+        --------
+        :class:`Webhook`
+            A partial :class:`Webhook`.
+            A partial webhook is just a webhook object with an ID and a token.
         """
 
         if not isinstance(adapter, WebhookAdapter):
@@ -502,6 +506,12 @@ class Webhook:
         -------
         InvalidArgument
             The URL is invalid.
+
+        Returns
+        --------
+        :class:`Webhook`
+            A partial :class:`Webhook`.
+            A partial webhook is just a webhook object with an ID and a token.
         """
 
         m = re.search(r'discord(?:app)?.com/api/webhooks/(?P<id>[0-9]{17,21})/(?P<token>[A-Za-z0-9\.\-\_]{60,68})', url)
@@ -560,7 +570,7 @@ class Webhook:
 
     @property
     def avatar_url(self):
-        """Returns an :class:`Asset` for the avatar the webhook has.
+        """:class:`Asset`: Returns an :class:`Asset` for the avatar the webhook has.
 
         If the webhook does not have a traditional avatar, an asset for
         the default avatar is returned instead.

docs/api.rst

@@ -739,9 +739,13 @@ Profile
     .. attribute:: user
 
         The :class:`User` the profile belongs to.
+
+        :type: :class:`User`
     .. attribute:: premium
 
         A boolean indicating if the user has premium (i.e. Discord Nitro).
+
+        :type: :class:`bool`
     .. attribute:: nitro
 
         An alias for :attr:`premium`.
@@ -749,47 +753,70 @@ Profile
 
         A naive UTC datetime indicating how long the user has been premium since.
         This could be ``None`` if not applicable.
+
+        :type: :class:`datetime.datetime`
     .. attribute:: staff
 
         A boolean indicating if the user is Discord Staff.
+
+        :type: :class:`bool`
     .. attribute:: partner
 
         A boolean indicating if the user is a Discord Partner.
+
+        :type: :class:`bool`
     .. attribute:: bug_hunter
 
         A boolean indicating if the user is a Bug Hunter.
+
+        :type: :class:`bool`
     .. attribute:: early_supporter
 
         A boolean indicating if the user has had premium before 10 October, 2018.
+
+        :type: :class:`bool`
     .. attribute:: hypesquad
 
         A boolean indicating if the user is in Discord HypeSquad.
+
+        :type: :class:`bool`
     .. attribute:: hypesquad_houses
 
         A list of :class:`HypeSquadHouse` that the user is in.
+
+        :type: List[:class:`HypeSquadHouse`]
     .. attribute:: team_user
 
         A boolean indicating if the user is in part of a team.
 
         .. versionadded:: 1.3
 
+        :type: :class:`bool`
+
     .. attribute:: system
 
         A boolean indicating if the user is officially part of the Discord urgent message system.
 
         .. versionadded:: 1.3
 
+        :type: :class:`bool`
+
     .. attribute:: mutual_guilds
 
         A list of :class:`Guild` that the :class:`ClientUser` shares with this
         user.
+
+        :type: List[:class:`Guild`]
+
     .. attribute:: connected_accounts
 
         A list of dict objects indicating the accounts the user has connected.
 
         An example entry can be seen below: ::
 
-            {type: "twitch", id: "92473777", name: "discordapp"}
+            {"type": "twitch", "id": "92473777", "name": "discordapp"}
+
+        :type: List[Dict[:class:`str`, :class:`str`]]
 
 .. _discord-api-enums:
 
@@ -1783,6 +1810,34 @@ of :class:`enum.Enum`.
 
         Represents a webhook that is internally managed by Discord, used for following channels.
 
+.. class:: DefaultAvatar
+
+    Represents the default avatar of a Discord :class:`User`
+
+    .. attribute:: blurple
+
+        Represents the default avatar with the color blurple.
+        See also :attr:`Colour.blurple`
+    .. attribute:: grey
+
+        Represents the default avatar with the color grey.
+        See also :attr:`Colour.greyple`
+    .. attribute:: gray
+
+        An alias for :attr:`grey`.
+    .. attribute:: green
+
+        Represents the default avatar with the color green.
+        See also :attr:`Colour.green`
+    .. attribute:: orange
+
+        Represents the default avatar with the color orange.
+        See also :attr:`Colour.orange`
+    .. attribute:: red
+
+        Represents the default avatar with the color red.
+        See also :attr:`Colour.red`
+
 Async Iterator
 ----------------
 
@@ -1873,7 +1928,7 @@ Certain utilities make working with async iterators easier, detailed below.
                 message_length = len(content)
 
         :param func: The function to call on every element. Could be a |coroutine_link|_.
-        :return: An async iterator.
+        :rtype: :class:`AsyncIterator`
 
     .. method:: filter(predicate)
 
@@ -1890,7 +1945,7 @@ Certain utilities make working with async iterators easier, detailed below.
                 ...
 
         :param predicate: The predicate to call on every element. Could be a |coroutine_link|_.
-        :return: An async iterator.
+        :rtype: :class:`AsyncIterator`
 
 .. _discord-api-audit-logs:
 
@@ -1962,102 +2017,138 @@ this goal, it must make use of a couple of data classes that aid in this goal.
     on the action being done, check the documentation for :class:`AuditLogAction`,
     otherwise check the documentation below for all attributes that are possible.
 
+    .. container:: operations
+
         .. describe:: iter(diff)
 
             Returns an iterator over (attribute, value) tuple of this diff.
 
     .. attribute:: name
 
-        :class:`str` – A name of something.
+        A name of something.
+
+        :type: :class:`str`
 
     .. attribute:: icon
 
-        :class:`str` – A guild's icon hash. See also :attr:`Guild.icon`.
+        A guild's icon hash. See also :attr:`Guild.icon`.
+
+        :type: :class:`str`
 
     .. attribute:: splash
 
-        :class:`str` – The guild's invite splash hash. See also :attr:`Guild.splash`.
+        The guild's invite splash hash. See also :attr:`Guild.splash`.
+
+        :type: :class:`str`
 
     .. attribute:: owner
 
-        Union[:class:`Member`, :class:`User`] – The guild's owner. See also :attr:`Guild.owner`
+        The guild's owner. See also :attr:`Guild.owner`
+
+        :type: Union[:class:`Member`, :class:`User`]
 
     .. attribute:: region
 
-        :class:`VoiceRegion` – The guild's voice region. See also :attr:`Guild.region`.
+        The guild's voice region. See also :attr:`Guild.region`.
+
+        :type: :class:`VoiceRegion`
 
     .. attribute:: afk_channel
 
-        Union[:class:`VoiceChannel`, :class:`Object`] – The guild's AFK channel.
+        The guild's AFK channel.
 
         If this could not be found, then it falls back to a :class:`Object`
         with the ID being set.
 
         See :attr:`Guild.afk_channel`.
 
+        :type: Union[:class:`VoiceChannel`, :class:`Object`]
+
     .. attribute:: system_channel
 
-        Union[:class:`TextChannel`, :class:`Object`] – The guild's system channel.
+        The guild's system channel.
 
         If this could not be found, then it falls back to a :class:`Object`
         with the ID being set.
 
         See :attr:`Guild.system_channel`.
 
+        :type: Union[:class:`TextChannel`, :class:`Object`]
+
     .. attribute:: afk_timeout
 
-        :class:`int` – The guild's AFK timeout. See :attr:`Guild.afk_timeout`.
+        The guild's AFK timeout. See :attr:`Guild.afk_timeout`.
+
+        :type: :class:`int`
 
     .. attribute:: mfa_level
 
-        :class:`int` - The guild's MFA level. See :attr:`Guild.mfa_level`.
+        The guild's MFA level. See :attr:`Guild.mfa_level`.
+
+        :type: :class:`int`
 
     .. attribute:: widget_enabled
 
-        :class:`bool` – The guild's widget has been enabled or disabled.
+        The guild's widget has been enabled or disabled.
+
+        :type: :class:`bool`
 
     .. attribute:: widget_channel
 
-        Union[:class:`TextChannel`, :class:`Object`] – The widget's channel.
+        The widget's channel.
 
         If this could not be found then it falls back to a :class:`Object`
         with the ID being set.
 
+        :type: Union[:class:`TextChannel`, :class:`Object`]
+
     .. attribute:: verification_level
 
-        :class:`VerificationLevel` – The guild's verification level.
+        The guild's verification level.
 
         See also :attr:`Guild.verification_level`.
 
+        :type: :class:`VerificationLevel`
+
     .. attribute:: default_notifications
 
-        :class:`NotificationLevel` – The guild's default notification level.
+        The guild's default notification level.
 
         See also :attr:`Guild.default_notifications`.
 
+        :type: :class:`NotificationLevel`
+
     .. attribute:: explicit_content_filter
 
-        :class:`ContentFilter` – The guild's content filter.
+        The guild's content filter.
 
         See also :attr:`Guild.explicit_content_filter`.
 
+        :type: :class:`ContentFilter`
+
     .. attribute:: default_message_notifications
 
-        :class:`int` – The guild's default message notification setting.
+        The guild's default message notification setting.
+
+        :type: :class:`int`
 
     .. attribute:: vanity_url_code
 
-        :class:`str` – The guild's vanity URL.
+        The guild's vanity URL.
 
         See also :meth:`Guild.vanity_invite` and :meth:`Guild.edit`.
 
+        :type: :class:`str`
+
     .. attribute:: position
 
-        :class:`int` – The position of a :class:`Role` or :class:`abc.GuildChannel`.
+        The position of a :class:`Role` or :class:`abc.GuildChannel`.
+
+        :type: :class:`int`
 
     .. attribute:: type
 
-        Union[:class:`int`, :class:`str`] – The type of channel or channel permission overwrite.
+        The type of channel or channel permission overwrite.
 
         If the type is an :class:`int`, then it is a type of channel which can be either
         ``0`` to indicate a text channel or ``1`` to indicate a voice channel.
@@ -2065,22 +2156,27 @@ this goal, it must make use of a couple of data classes that aid in this goal.
         If the type is a :class:`str`, then it is a type of permission overwrite which
         can be either ``'role'`` or ``'member'``.
 
+        :type: Union[:class:`int`, :class:`str`]
+
     .. attribute:: topic
 
-        :class:`str` – The topic of a :class:`TextChannel`.
+        The topic of a :class:`TextChannel`.
 
         See also :attr:`TextChannel.topic`.
 
+        :type: :class:`str`
+
     .. attribute:: bitrate
 
-        :class:`int` – The bitrate of a :class:`VoiceChannel`.
+        The bitrate of a :class:`VoiceChannel`.
 
         See also :attr:`VoiceChannel.bitrate`.
 
+        :type: :class:`int`
+
     .. attribute:: overwrites
 
-        List[Tuple[target, :class:`PermissionOverwrite`]] – A list of
-        permission overwrite tuples that represents a target and a
+        A list of permission overwrite tuples that represents a target and a
         :class:`PermissionOverwrite` for said target.
 
         The first element is the object being targeted, which can either
@@ -2089,122 +2185,161 @@ this goal, it must make use of a couple of data classes that aid in this goal.
         a ``type`` attribute set to either ``'role'`` or ``'member'`` to help
         decide what type of ID it is.
 
+        :type: List[Tuple[target, :class:`PermissionOverwrite`]]
+
     .. attribute:: roles
 
-        List[Union[:class:`Role`, :class:`Object`]] – A list of roles being added or removed
-        from a member.
+        A list of roles being added or removed from a member.
 
         If a role is not found then it is a :class:`Object` with the ID and name being
         filled in.
 
+        :type: List[Union[:class:`Role`, :class:`Object`]]
+
     .. attribute:: nick
 
-        Optional[:class:`str`] – The nickname of a member.
+        The nickname of a member.
 
         See also :attr:`Member.nick`
 
+        :type: Optional[:class:`str`]
+
     .. attribute:: deaf
 
-        :class:`bool` – Whether the member is being server deafened.
+        Whether the member is being server deafened.
 
         See also :attr:`VoiceState.deaf`.
 
+        :type: :class:`bool`
+
     .. attribute:: mute
 
-        :class:`bool` – Whether the member is being server muted.
+        Whether the member is being server muted.
 
         See also :attr:`VoiceState.mute`.
 
+        :type: :class:`bool`
+
     .. attribute:: permissions
 
-        :class:`Permissions` – The permissions of a role.
+        The permissions of a role.
 
         See also :attr:`Role.permissions`.
 
+        :type: :class:`Permissions`
+
     .. attribute:: colour
                    color
 
-        :class:`Colour` – The colour of a role.
+        The colour of a role.
 
         See also :attr:`Role.colour`
 
+        :type: :class:`Colour`
+
     .. attribute:: hoist
 
-        :class:`bool` – Whether the role is being hoisted or not.
+        Whether the role is being hoisted or not.
 
         See also :attr:`Role.hoist`
 
+        :type: :class:`bool`
+
     .. attribute:: mentionable
 
-        :class:`bool` – Whether the role is mentionable or not.
+        Whether the role is mentionable or not.
 
         See also :attr:`Role.mentionable`
 
+        :type: :class:`bool`
+
     .. attribute:: code
 
-        :class:`str` – The invite's code.
+        The invite's code.
 
         See also :attr:`Invite.code`
 
+        :type: :class:`str`
+
     .. attribute:: channel
 
-        Union[:class:`abc.GuildChannel`, :class:`Object`] – A guild channel.
+        A guild channel.
 
         If the channel is not found then it is a :class:`Object` with the ID
         being set. In some cases the channel name is also set.
 
+        :type: Union[:class:`abc.GuildChannel`, :class:`Object`]
+
     .. attribute:: inviter
 
-        :class:`User` – The user who created the invite.
+        The user who created the invite.
 
         See also :attr:`Invite.inviter`.
 
+        :type: :class:`User`
+
     .. attribute:: max_uses
 
-        :class:`int` – The invite's max uses.
+        The invite's max uses.
 
         See also :attr:`Invite.max_uses`.
 
+        :type: :class:`int`
+
     .. attribute:: uses
 
-        :class:`int` – The invite's current uses.
+        The invite's current uses.
 
         See also :attr:`Invite.uses`.
 
+        :type: :class:`int`
+
     .. attribute:: max_age
 
-        :class:`int` – The invite's max age in seconds.
+        The invite's max age in seconds.
 
         See also :attr:`Invite.max_age`.
 
+        :type: :class:`int`
+
     .. attribute:: temporary
 
-        :class:`bool` – If the invite is a temporary invite.
+        If the invite is a temporary invite.
 
         See also :attr:`Invite.temporary`.
 
+        :type: :class:`bool`
+
     .. attribute:: allow
                    deny
 
-        :class:`Permissions` – The permissions being allowed or denied.
+        The permissions being allowed or denied.
+
+        :type: :class:`Permissions`
 
     .. attribute:: id
 
-        :class:`int` – The ID of the object being changed.
+        The ID of the object being changed.
+
+        :type: :class:`int`
 
     .. attribute:: avatar
 
-        :class:`str` – The avatar hash of a member.
+        The avatar hash of a member.
 
         See also :attr:`User.avatar`.
 
+        :type: :class:`str`
+
     .. attribute:: slowmode_delay
 
-        :class:`int` – The number of seconds members have to wait before
+        The number of seconds members have to wait before
         sending another message in the channel.
 
         See also :attr:`TextChannel.slowmode_delay`.
 
+        :type: :class:`int`
+
 .. this is currently missing the following keys: reason and application_id
    I'm not sure how to about porting these
 

docs/ext/commands/api.rst

@@ -93,7 +93,7 @@ Cogs
 .. autoclass:: discord.ext.commands.CogMeta
     :members:
 
-.. _ext_commands_api_formatters:
+.. _ext_commands_help_command:
 
 Help Commands
 -----------------