Improve documentation

1 files changed, 131 insertions, 83 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 55ce36b2..99ba9424 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -28,7 +28,7 @@ There are two main ways to query version information about the library. For guar
 .. data:: __version__
 
     A string representation of the version. e.g. ``'1.0.0rc1'``. This is based
-    off of `PEP-440 <https://www.python.org/dev/peps/pep-0440/>`_.
+    off of :pep:`440`.
 
 Client
 -------
@@ -94,7 +94,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
 .. warning::
 
-    All the events must be a |corourl|_. If they aren't, then you might get unexpected
+    All the events must be a |coroutine_link|_. If they aren't, then you might get unexpected
     errors. In order to turn a function into a coroutine they must be ``async def``
     functions.
 
@@ -131,6 +131,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     to denote when a particular shard ID has become ready.
 
     :param shard_id: The shard ID that is ready.
+    :type shard_id: :class:`int`
 
 .. function:: on_resumed()
 
@@ -145,14 +146,16 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     suppress the default action of printing the traceback.
 
     The information of the exception raised and the exception itself can
-    be retrieved with a standard call to ``sys.exc_info()``.
+    be retrieved with a standard call to :func:`sys.exc_info`.
 
     If you want exception to propagate out of the :class:`Client` class
     you can define an ``on_error`` handler consisting of a single empty
-    ``raise`` statement.  Exceptions raised by ``on_error`` will not be
+    :ref:`py:raise`.  Exceptions raised by ``on_error`` will not be
     handled in any way by :class:`Client`.
 
     :param event: The name of the event that raised the exception.
+    :type event: :class:`str`
+
     :param args: The positional arguments for the event that raised the
         exception.
     :param kwargs: The keyword arguments for the event that raised the
@@ -175,6 +178,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     :param msg: The message passed in from the WebSocket library.
                 Could be :class:`bytes` for a binary message or :class:`str`
                 for a regular message.
+    :type msg: Union[:class:`bytes`, :class:`str`]
 
 .. function:: on_socket_raw_send(payload)
 
@@ -206,8 +210,11 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     is a :class:`Member`, otherwise it is a :class:`User`.
 
     :param channel: The location where the typing originated from.
+    :type channel: :class:`abc.Messageable`
     :param user: The user that started typing.
-    :param when: A ``datetime.datetime`` object representing when typing started.
+    :type user: Union[:class:`User`, :class:`Member`]
+    :param when: When the typing started as a naive datetime in UTC.
+    :type when: :class:`datetime.datetime`
 
 .. function:: on_message(message)
 
@@ -221,7 +228,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
         checking the user IDs. Note that :class:`~ext.commands.Bot` does not
         have this problem.
 
-    :param message: A :class:`Message` of the current message.
+    :param message: The current message.
+    :type message: :class:`Message`
 
 .. function:: on_message_delete(message)
 
@@ -232,7 +240,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
     If this occurs increase the :attr:`Client.max_messages` attribute.
 
-    :param message: A :class:`Message` of the deleted message.
+    :param message: The deleted message.
+    :type message: :class:`Message`
 
 .. function:: on_bulk_message_delete(messages)
 
@@ -245,7 +254,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
     If this occurs increase the :attr:`Client.max_messages` attribute.
 
-    :param messages: A :class:`list` of :class:`Message` that have been deleted.
+    :param messages: The messages that have been deleted.
+    :type messages: List[:class:`Message`]
 
 .. function:: on_raw_message_delete(payload)
 
@@ -288,8 +298,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
     - A call message has received an update to its participants or ending time.
 
-    :param before: A :class:`Message` of the previous version of the message.
-    :param after: A :class:`Message` of the current version of the message.
+    :param before: The previous version of the message.
+    :type before: :class:`Message`
+    :param after: The current version of the message.
+    :type after: :class:`Message`
 
 .. function:: on_raw_message_edit(payload)
 
@@ -300,7 +312,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     it can be accessed via :attr:`RawMessageUpdateEvent.cached_message`
 
     Due to the inherently raw nature of this event, the data parameter coincides with
-    the raw data given by the `gateway <https://discordapp.com/developers/docs/topics/gateway#message-update>`_
+    the raw data given by the `gateway <https://discordapp.com/developers/docs/topics/gateway#message-update>`_.
 
     Since the data payload can be partial, care must be taken when accessing stuff in the dictionary.
     One example of a common case of partial data is when the ``'content'`` key is inaccessible. This
@@ -320,8 +332,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
         To get the :class:`Message` being reacted, access it via :attr:`Reaction.message`.
 
-    :param reaction: A :class:`Reaction` showing the current state of the reaction.
-    :param user: A :class:`User` or :class:`Member` of the user who added the reaction.
+    :param reaction: The current state of the reaction.
+    :type reaction: :class:`Reaction`
+    :param user: The user who added the reaction.
+    :type user: Union[:class:`Member`, :class:`User`]
 
 .. function:: on_raw_reaction_add(payload)
 
@@ -341,8 +355,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
         To get the message being reacted, access it via :attr:`Reaction.message`.
 
-    :param reaction: A :class:`Reaction` showing the current state of the reaction.
-    :param user: A :class:`User` or :class:`Member` of the user whose reaction was removed.
+    :param reaction: The current state of the reaction.
+    :type reaction: :class:`Reaction`
+    :param user: The user who added the reaction.
+    :type user: Union[:class:`Member`, :class:`User`]
 
 .. function:: on_raw_reaction_remove(payload)
 
@@ -358,8 +374,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     if the message is not found in the internal message cache, then this event
     will not be called.
 
-    :param message: The :class:`Message` that had its reactions cleared.
-    :param reactions: A list of :class:`Reaction`\s that were removed.
+    :param message: The message that had its reactions cleared.
+    :type message: :class:`Message`
+    :param reactions: The reactions that were removed.
+    :type reactions: List[:class:`Reaction`]
 
 .. function:: on_raw_reaction_clear(payload)
 
@@ -374,22 +392,26 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
     Called whenever a private channel is deleted or created.
 
-    :param channel: The :class:`abc.PrivateChannel` that got created or deleted.
+    :param channel: The private channel that got created or deleted.
+    :type channel: :class:`abc.PrivateChannel`
 
 .. function:: on_private_channel_update(before, after)
 
     Called whenever a private group DM is updated. e.g. changed name or topic.
 
-    :param before: The :class:`GroupChannel` that got updated with the old info.
-    :param after: The :class:`GroupChannel` that got updated with the updated info.
+    :param before: The updated group channel's old info.
+    :type before: :class:`GroupChannel`
+    :param after: The updated group channel's new info.
+    :type after: :class:`GroupChannel`
 
 .. function:: on_private_channel_pins_update(channel, last_pin)
 
     Called whenever a message is pinned or unpinned from a private channel.
 
-    :param channel: The :class:`abc.PrivateChannel` that had it's pins updated.
-    :param last_pin: A ``datetime.datetime`` object representing when the latest message
-                     was pinned or ``None`` if there are no pins.
+    :param channel: The private channel that had its pins updated.
+    :type channel: :class:`abc.PrivateChannel`
+    :param last_pin: The latest message that was pinned as a naive datetime in UTC. Could be ``None``.
+    :type last_pin: Optional[:class:`datetime.datetime`]
 
 .. function:: on_guild_channel_delete(channel)
               on_guild_channel_create(channel)
@@ -398,41 +420,48 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
     Note that you can get the guild from :attr:`~abc.GuildChannel.guild`.
 
-    :param channel: The :class:`abc.GuildChannel` that got created or deleted.
+    :param channel: The guild channel that got created or deleted.
+    :type channel: :class:`abc.GuildChannel`
 
 .. function:: on_guild_channel_update(before, after)
 
     Called whenever a guild channel is updated. e.g. changed name, topic, permissions.
 
-    :param before: The :class:`abc.GuildChannel` that got updated with the old info.
-    :param after: The :class:`abc.GuildChannel` that got updated with the updated info.
+    :param before: The updated guild channel's old info.
+    :type before: :class:`abc.GuildChannel`
+    :param after: The updated guild channel's new info.
+    :type after: :class:`abc.GuildChannel`
 
 .. function:: on_guild_channel_pins_update(channel, last_pin)
 
     Called whenever a message is pinned or unpinned from a guild channel.
 
-    :param channel: The :class:`abc.GuildChannel` that had it's pins updated.
-    :param last_pin: A ``datetime.datetime`` object representing when the latest message
-                     was pinned or ``None`` if there are no pins.
+    :param channel: The guild channel that had its pins updated.
+    :type channel: :class:`abc.GuildChannel`
+    :param last_pin: The latest message that was pinned as a naive datetime in UTC. Could be ``None``.
+    :type last_pin: Optional[:class:`datetime.datetime`]
 
 .. function:: on_guild_integrations_update(guild)
 
     Called whenever an integration is created, modified, or removed from a guild.
 
-    :param guild: The :class:`Guild` that had its integrations updated.
+    :param guild: The guild that had its integrations updated.
+    :type guild: :class:`Guild`
 
 .. function:: on_webhooks_update(channel)
 
     Called whenever a webhook is created, modified, or removed from a guild channel.
 
-    :param channel: The :class:`abc.GuildChannel` that had its webhooks updated.
+    :param channel: The channel that had its webhooks updated.
+    :type channel: :class:`abc.GuildChannel`
 
 .. function:: on_member_join(member)
               on_member_remove(member)
 
     Called when a :class:`Member` leaves or joins a :class:`Guild`.
 
-    :param member: The :class:`Member` that joined or left.
+    :param member: The member who joined or left.
+    :type member: :class:`Member`
 
 .. function:: on_member_update(before, after)
 
@@ -445,8 +474,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     - nickname
     - roles
 
-    :param before: The :class:`Member` that updated their profile with the old info.
-    :param after: The :class:`Member` that updated their profile with the updated info.
+    :param before: The updated member's old info.
+    :type before: :class:`Member`
+    :param after: The updated member's updated info.
+    :type after: :class:`Member`
 
 .. function:: on_user_update(before, after)
 
@@ -458,15 +489,18 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     - username
     - discriminator
 
-    :param before: The :class:`User` that updated their profile with the old info.
-    :param after: The :class:`User` that updated their profile with the updated info.
+    :param before: The updated user's old info.
+    :type before: :class:`User`
+    :param after: The updated user's updated info.
+    :type after: :class:`User`
 
 .. function:: on_guild_join(guild)
 
     Called when a :class:`Guild` is either created by the :class:`Client` or when the
     :class:`Client` joins a guild.
 
-    :param guild: The :class:`Guild` that was joined.
+    :param guild: The guild that was joined.
+    :type guild: :class:`Guild`
 
 .. function:: on_guild_remove(guild)
 
@@ -482,7 +516,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     In order for this event to be invoked then the :class:`Client` must have
     been part of the guild to begin with. (i.e. it is part of :attr:`Client.guilds`)
 
-    :param guild: The :class:`Guild` that got removed.
+    :param guild: The guild that got removed.
+    :type guild: :class:`Guild`
 
 .. function:: on_guild_update(before, after)
 
@@ -493,8 +528,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     - Changed AFK timeout
     - etc
 
-    :param before: The :class:`Guild` prior to being updated.
-    :param after: The :class:`Guild` after being updated.
+    :param before: The guild prior to being updated.
+    :type before: :class:`Guild`
+    :param after: The guild after being updated.
+    :type after: :class:`Guild`
 
 .. function:: on_guild_role_create(role)
               on_guild_role_delete(role)
@@ -503,22 +540,28 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
     To get the guild it belongs to, use :attr:`Role.guild`.
 
-    :param role: The :class:`Role` that was created or deleted.
+    :param role: The role that was created or deleted.
+    :type role: :class:`Role`
 
 .. function:: on_guild_role_update(before, after)
 
     Called when a :class:`Role` is changed guild-wide.
 
-    :param before: The :class:`Role` that updated with the old info.
-    :param after: The :class:`Role` that updated with the updated info.
+    :param before: The updated role's old info.
+    :type before: :class:`Role`
+    :param after: The updated role's updated info.
+    :type after: :class:`Role`
 
 .. function:: on_guild_emojis_update(guild, before, after)
 
     Called when a :class:`Guild` adds or removes :class:`Emoji`.
 
-    :param guild: The :class:`Guild` who got their emojis updated.
-    :param before: A list of :class:`Emoji` before the update.
-    :param after: A list of :class:`Emoji` after the update.
+    :param guild: The guild who got their emojis updated.
+    :type guild: :class:`Guild`
+    :param before: A list of emojis before the update.
+    :type before: List[:class:`Emoji`]
+    :param after: A list of emojis after the update.
+    :type after: List[:class:`Emoji`]
 
 .. function:: on_guild_available(guild)
               on_guild_unavailable(guild)
@@ -539,25 +582,32 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     - A member is muted or deafened by their own accord.
     - A member is muted or deafened by a guild administrator.
 
-    :param member: The :class:`Member` whose voice states changed.
-    :param before: The :class:`VoiceState` prior to the changes.
-    :param after: The :class:`VoiceState` after to the changes.
+    :param member: The member whose voice states changed.
+    :type member: :class:`Member`
+    :param before: The voice state prior to the changes.
+    :type before: :class:`VoiceState`
+    :param after: The voice state after to the changes.
+    :type after: :class:`VoiceState`
 
 .. function:: on_member_ban(guild, user)
 
     Called when user gets banned from a :class:`Guild`.
 
-    :param guild: The :class:`Guild` the user got banned from.
+    :param guild: The guild the user got banned from.
+    :type guild: :class:`Guild`
     :param user: The user that got banned.
                  Can be either :class:`User` or :class:`Member` depending if
                  the user was in the guild or not at the time of removal.
+    :type user: Union[:class:`User`, :class:`Member`]
 
 .. function:: on_member_unban(guild, user)
 
     Called when a :class:`User` gets unbanned from a :class:`Guild`.
 
-    :param guild: The :class:`Guild` the user got unbanned from.
-    :param user: The :class:`User` that got unbanned.
+    :param guild: The guild the user got unbanned from.
+    :type guild: :class:`Guild`
+    :param user: The user that got unbanned.
+    :type user: :class:`User`
 
 .. function:: on_group_join(channel, user)
               on_group_remove(channel, user)
@@ -565,7 +615,9 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     Called when someone joins or leaves a :class:`GroupChannel`.
 
     :param channel: The group that the user joined or left.
+    :type channel: :class:`GroupChannel`
     :param user: The user that joined or left.
+    :type user: :class:`User`
 
 .. function:: on_relationship_add(relationship)
               on_relationship_remove(relationship)
@@ -574,6 +626,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     :class:`ClientUser`.
 
     :param relationship: The relationship that was added or removed.
+    :type relationship: :class:`Relationship`
 
 .. function:: on_relationship_update(before, after)
 
@@ -581,7 +634,9 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     block a friend or a friendship is accepted.
 
     :param before: The previous relationship status.
+    :type before: :class:`Relationship`
     :param after: The updated relationship status.
+    :type after: :class:`Relationship`
 
 .. _discord-api-utils:
 
@@ -600,6 +655,8 @@ Utility Functions
 
 .. autofunction:: discord.utils.escape_mentions
 
+.. autofunction:: discord.utils.resolve_invite
+
 
 Profile
 ---------
@@ -659,9 +716,7 @@ Enumerations
 The API provides some enumerations for certain types of strings to avoid the API
 from being stringly typed in case the strings change in the future.
 
-All enumerations are subclasses of `enum`_.
-
-.. _enum: https://docs.python.org/3/library/enum.html
+All enumerations are subclasses of :class:`enum.Enum`.
 
 .. class:: ChannelType
 
@@ -1114,7 +1169,7 @@ All enumerations are subclasses of `enum`_.
         A member prune was triggered.
 
         When this is the action, the type of :attr:`~AuditLogEntry.target` is
-        set to `None`.
+        set to ``None``.
 
         When this is the action, the type of :attr:`~AuditLogEntry.extra` is
         set to an unspecified proxy object with two attributes:
@@ -1485,8 +1540,7 @@ Async Iterator
 ----------------
 
 Some API functions return an "async iterator". An async iterator is something that is
-capable of being used in an `async for <https://docs.python.org/3/reference/compound_stmts.html#the-async-for-statement>`_
-statement.
+capable of being used in an :ref:`async for statement <py:async for>`.
 
 These async iterators can be used as follows: ::
 
@@ -1531,7 +1585,7 @@ Certain utilities make working with async iterators easier, detailed below.
         Similar to :func:`utils.find` except run over the async iterator.
 
         Unlike :func:`utils.find`\, the predicate provided can be a
-        coroutine.
+        |coroutine_link|_.
 
         Getting the last audit log with a reason or ``None``: ::
 
@@ -1540,7 +1594,7 @@ Certain utilities make working with async iterators easier, detailed below.
 
             event = await guild.audit_logs().find(predicate)
 
-        :param predicate: The predicate to use. Can be a coroutine.
+        :param predicate: The predicate to use. Could be a |coroutine_link|_.
         :return: The first element that returns ``True`` for the predicate or ``None``.
 
     .. comethod:: flatten()
@@ -1554,10 +1608,10 @@ Certain utilities make working with async iterators easier, detailed below.
 
     .. method:: map(func)
 
-        This is similar to the built-in :func:`map <python:map>` function. Another
+        This is similar to the built-in :func:`map <py:map>` function. Another
         :class:`AsyncIterator` is returned that executes the function on
         every element it is iterating over. This function can either be a
-        regular function or a coroutine.
+        regular function or a |coroutine_link|_.
 
         Creating a content iterator: ::
 
@@ -1567,14 +1621,14 @@ Certain utilities make working with async iterators easier, detailed below.
             async for content in channel.history().map(transform):
                 message_length = len(content)
 
-        :param func: The function to call on every element. Could be a coroutine.
+        :param func: The function to call on every element. Could be a |coroutine_link|_.
         :return: An async iterator.
 
     .. method:: filter(predicate)
 
-        This is similar to the built-in :func:`filter <python:filter>` function. Another
+        This is similar to the built-in :func:`filter <py:filter>` function. Another
         :class:`AsyncIterator` is returned that filters over the original
-        async iterator. This predicate can be a regular function or a coroutine.
+        async iterator. This predicate can be a regular function or a |coroutine_link|_.
 
         Getting messages by non-bot accounts: ::
 
@@ -1584,7 +1638,7 @@ Certain utilities make working with async iterators easier, detailed below.
             async for elem in channel.history().filter(predicate):
                 ...
 
-        :param predicate: The predicate to call on every element. Could be a coroutine.
+        :param predicate: The predicate to call on every element. Could be a |coroutine_link|_.
         :return: An async iterator.
 
 
@@ -1678,7 +1732,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
 
     .. attribute:: region
 
-        :class:`GuildRegion` – The guild's voice region. See also :attr:`Guild.region`.
+        :class:`VoiceRegion` – The guild's voice region. See also :attr:`Guild.region`.
 
     .. attribute:: afk_channel
 
@@ -1743,7 +1797,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
 
         :class:`str` – The guild's vanity URL.
 
-        See also :meth:`Guild.vanity_invite` and :meth:`Guild.change_vanity_invite`.
+        See also :meth:`Guild.vanity_invite` and :meth:`Guild.edit`.
 
     .. attribute:: position
 
@@ -1751,7 +1805,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
 
     .. attribute:: type
 
-        *Union[int, str]* – The type of channel or channel permission overwrite.
+        Union[:class:`int`, :class:`str`] – 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.
@@ -1793,7 +1847,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
 
     .. attribute:: nick
 
-        *Optional[str]* – The nickname of a member.
+        Optional[:class:`str`] – The nickname of a member.
 
         See also :attr:`Member.nick`
 
@@ -1930,12 +1984,12 @@ interface, :meth:`WebhookAdapter.request`.
 Abstract Base Classes
 -----------------------
 
-An abstract base class (also known as an ``abc``) is a class that models can inherit
-to get their behaviour. The Python implementation of an `abc <https://docs.python.org/3/library/abc.html>`_ is
+An :term:`py:abstract base class` (also known as an ``abc``) is a class that models can inherit
+to get their behaviour. The Python implementation of an :doc:`abc <py:library/abc>` is
 slightly different in that you can register them at run-time. **Abstract base classes cannot be instantiated**.
-They are mainly there for usage with ``isinstance`` and ``issubclass``\.
+They are mainly there for usage with :func:`py:isinstance` and :func:`py:issubclass`\.
 
-This library has a module related to abstract base classes, some of which are actually from the ``abc`` standard
+This library has a module related to abstract base classes, some of which are actually from the :doc:`abc <py:library/abc>` standard
 module, others which are not.
 
 .. autoclass:: discord.abc.Snowflake
@@ -1985,12 +2039,9 @@ the user of the library.
 
 .. note::
 
-    Nearly all classes here have ``__slots__`` defined which means that it is
+    Nearly all classes here have :ref:`py:slots` defined which means that it is
     impossible to have dynamic attributes to the data classes.
 
-    More information about ``__slots__`` can be found
-    `in the official python documentation <https://docs.python.org/3/reference/datamodel.html#slots>`_.
-
 
 ClientUser
 ~~~~~~~~~~~~
@@ -2247,15 +2298,12 @@ Some classes are just there to be data containers, this lists them.
 Unlike :ref:`models <discord_api_models>` you are allowed to create
 these yourself, even if they can also be used to hold attributes.
 
-Nearly all classes here have ``__slots__`` defined which means that it is
+Nearly all classes here have :ref:`py:slots` defined which means that it is
 impossible to have dynamic attributes to the data classes.
 
-The only exception to this rule is :class:`Object`, which is made with
+The only exception to this rule is :class:`abc.Snowflake`, which is made with
 dynamic attributes in mind.
 
-More information about ``__slots__`` can be found
-`in the official python documentation <https://docs.python.org/3/reference/datamodel.html#slots>`_.
-
 
 Object
 ~~~~~~~