Add documentation for gateway intents

5 files changed, 206 insertions, 2 deletions

diff --git a/discord/flags.py b/discord/flags.py
index 47a3bcae..f568c26f 100644
--- a/discord/flags.py
+++ b/discord/flags.py
@@ -418,6 +418,15 @@ class Intents(BaseFlags):
         - :func:`on_guild_channel_create`
         - :func:`on_guild_channel_delete`
         - :func:`on_guild_channel_pins_update`
+
+        This also corresponds to the following attributes and classes in terms of cache:
+
+        - :attr:`Client.guilds`
+        - :class:`Guild` and all its attributes.
+        - :meth:`Client.get_channel`
+        - :meth:`Client.get_all_channels`
+
+        It is highly advisable to leave this intent enabled for your bot to function.
         """
         return 1 << 0
 
@@ -432,9 +441,25 @@ class Intents(BaseFlags):
         - :func:`on_member_update` (nickname, roles)
         - :func:`on_user_update`
 
+        This also corresponds to the following attributes and classes in terms of cache:
+
+        - :attr:`Client.get_all_members`
+        - :meth:`Guild.chunk`
+        - :meth:`Guild.fetch_members`
+        - :meth:`Guild.members`
+        - :meth:`Guild.get_member`
+        - :attr:`Member.roles`
+        - :attr:`Member.nick`
+        - :attr:`Member.premium_since`
+        - :attr:`User.name`
+        - :attr:`User.avatar` (:meth:`User.avatar_url` and :meth:`User.avatar_url_as`)
+        - :attr:`User.discriminator`
+
+        For more information go to the :ref:`member intent documentation <need_members_intent>`.
+
         .. note::
 
-            Currently, this requires opting in explicitly via the dev portal as well.
+            Currently, this requires opting in explicitly via the developer portal as well.
             Bots in over 100 guilds will need to apply to Discord for verification.
         """
         return 1 << 1
@@ -447,6 +472,8 @@ class Intents(BaseFlags):
 
         - :func:`on_member_ban`
         - :func:`on_member_unban`
+
+        This does not correspond to any attributes or classes in the library in terms of cache.
         """
         return 1 << 2
 
@@ -457,6 +484,13 @@ class Intents(BaseFlags):
         This corresponds to the following events:
 
         - :func:`on_guild_emojis_update`
+
+        This also corresponds to the following attributes and classes in terms of cache:
+
+        - :class:`Emoji`
+        - :meth:`Client.get_emoji`
+        - :meth:`Client.emojis`
+        - :attr:`Guild.emojis`
         """
         return 1 << 3
 
@@ -467,6 +501,8 @@ class Intents(BaseFlags):
         This corresponds to the following events:
 
         - :func:`on_guild_integrations_update`
+
+        This does not correspond to any attributes or classes in the library in terms of cache.
         """
         return 1 << 4
 
@@ -477,6 +513,8 @@ class Intents(BaseFlags):
         This corresponds to the following events:
 
         - :func:`on_webhooks_update`
+
+        This does not correspond to any attributes or classes in the library in terms of cache.
         """
         return 1 << 5
 
@@ -488,6 +526,8 @@ class Intents(BaseFlags):
 
         - :func:`on_invite_create`
         - :func:`on_invite_delete`
+
+        This does not correspond to any attributes or classes in the library in terms of cache.
         """
         return 1 << 6
 
@@ -498,6 +538,12 @@ class Intents(BaseFlags):
         This corresponds to the following events:
 
         - :func:`on_voice_state_update`
+
+        This also corresponds to the following attributes and classes in terms of cache:
+
+        - :attr:`VoiceChannel.members`
+        - :attr:`VoiceChannel.voice_states`
+        - :attr:`Member.voice`
         """
         return 1 << 7
 
@@ -509,9 +555,17 @@ class Intents(BaseFlags):
 
         - :func:`on_member_update` (activities, status)
 
+        This also corresponds to the following attributes and classes in terms of cache:
+
+        - :attr:`Member.activities`
+        - :attr:`Member.status`
+        - :attr:`Member.raw_status`
+
+        For more information go to the :ref:`presence intent documentation <need_presence_intent>`.
+
         .. note::
 
-            Currently, this requires opting in explicitly via the dev portal as well.
+            Currently, this requires opting in explicitly via the developer portal as well.
             Bots in over 100 guilds will need to apply to Discord for verification.
         """
         return 1 << 8
@@ -530,6 +584,17 @@ class Intents(BaseFlags):
         - :func:`on_raw_message_delete` (both guilds and DMs)
         - :func:`on_raw_message_update` (both guilds and DMs)
         - :func:`on_private_channel_create`
+
+        This also corresponds to the following attributes and classes in terms of cache:
+
+        - :class:`Message`
+        - :attr:`Client.cached_messages`
+
+        Note that due to an implicit relationship this also corresponds to the following events:
+
+        - :func:`on_reaction_add` (both guilds and DMs)
+        - :func:`on_reaction_remove` (both guilds and DMs)
+        - :func:`on_reaction_clear` (both guilds and DMs)
         """
         return (1 << 9) | (1 << 12)
 
@@ -546,6 +611,17 @@ class Intents(BaseFlags):
         - :func:`on_message_delete` (only for guilds)
         - :func:`on_raw_message_delete` (only for guilds)
         - :func:`on_raw_message_update` (only for guilds)
+
+        This also corresponds to the following attributes and classes in terms of cache:
+
+        - :class:`Message`
+        - :attr:`Client.cached_messages` (only for guilds)
+
+        Note that due to an implicit relationship this also corresponds to the following events:
+
+        - :func:`on_reaction_add` (only for guilds)
+        - :func:`on_reaction_remove` (only for guilds)
+        - :func:`on_reaction_clear` (only for guilds)
         """
         return 1 << 9
 
@@ -563,6 +639,17 @@ class Intents(BaseFlags):
         - :func:`on_raw_message_delete` (only for DMs)
         - :func:`on_raw_message_update` (only for DMs)
         - :func:`on_private_channel_create`
+
+        This also corresponds to the following attributes and classes in terms of cache:
+
+        - :class:`Message`
+        - :attr:`Client.cached_messages` (only for DMs)
+
+        Note that due to an implicit relationship this also corresponds to the following events:
+
+        - :func:`on_reaction_add` (only for DMs)
+        - :func:`on_reaction_remove` (only for DMs)
+        - :func:`on_reaction_clear` (only for DMs)
         """
         return 1 << 12
 
@@ -580,6 +667,10 @@ class Intents(BaseFlags):
         - :func:`on_raw_reaction_add` (both guilds and DMs)
         - :func:`on_raw_reaction_remove` (both guilds and DMs)
         - :func:`on_raw_reaction_clear` (both guilds and DMs)
+
+        This also corresponds to the following attributes and classes in terms of cache:
+
+        - :attr:`Message.reactions` (both guild and DM messages)
         """
         return (1 << 10) | (1 << 13)
 
@@ -597,6 +688,10 @@ class Intents(BaseFlags):
         - :func:`on_raw_reaction_add` (only for guilds)
         - :func:`on_raw_reaction_remove` (only for guilds)
         - :func:`on_raw_reaction_clear` (only for guilds)
+
+        This also corresponds to the following attributes and classes in terms of cache:
+
+        - :attr:`Message.reactions` (only for guild messages)
         """
         return 1 << 10
 
@@ -614,6 +709,10 @@ class Intents(BaseFlags):
         - :func:`on_raw_reaction_add` (only for DMs)
         - :func:`on_raw_reaction_remove` (only for DMs)
         - :func:`on_raw_reaction_clear` (only for DMs)
+
+        This also corresponds to the following attributes and classes in terms of cache:
+
+        - :attr:`Message.reactions` (only for DM messages)
         """
         return 1 << 13
 
@@ -626,6 +725,8 @@ class Intents(BaseFlags):
         This corresponds to the following events:
 
         - :func:`on_typing` (both guilds and DMs)
+
+        This does not correspond to any attributes or classes in the library in terms of cache.
         """
         return (1 << 11) | (1 << 14)
 
@@ -638,6 +739,8 @@ class Intents(BaseFlags):
         This corresponds to the following events:
 
         - :func:`on_typing` (only for guilds)
+
+        This does not correspond to any attributes or classes in the library in terms of cache.
         """
         return 1 << 11
 
@@ -650,6 +753,8 @@ class Intents(BaseFlags):
         This corresponds to the following events:
 
         - :func:`on_typing` (only for DMs)
+
+        This does not correspond to any attributes or classes in the library in terms of cache.
         """
         return 1 << 14
 
diff --git a/docs/images/discord_bot_tab.png b/docs/images/discord_bot_tab.png
new file mode 100644
index 00000000..83568244
--- /dev/null
+++ b/docs/images/discord_bot_tab.png
diff --git a/docs/images/discord_privileged_intents.png b/docs/images/discord_privileged_intents.png
new file mode 100644
index 00000000..297eabbb
--- /dev/null
+++ b/docs/images/discord_privileged_intents.png
diff --git a/docs/index.rst b/docs/index.rst
index 99868756..20c5d183 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -49,6 +49,7 @@ Additional Information
     :maxdepth: 2
 
     discord
+    intents
     faq
     whats_new
     version_guarantees
diff --git a/docs/intents.rst b/docs/intents.rst
new file mode 100644
index 00000000..fd6d0bbe
--- /dev/null
+++ b/docs/intents.rst
@@ -0,0 +1,98 @@
+.. currentmodule:: discord
+.. versionadded:: 1.5
+.. _intents_primer:
+
+A Primer to Gateway Intents
+=============================
+
+In version 1.5 comes with the introduction of :class:`Intents`. This is a radical change in how bots are written. An intent basically allows a bot to subscribe into specific buckets of events. The events that correspond to each intent is documented in the individual attribute of the :class:`Intents` documentation.
+
+These intents are passed to the constructor of :class:`Client` or its subclasses (:class:`AutoShardedClient`, :class:`~.AutoShardedBot`, :class:`~.Bot`) with the ``intents`` argument.
+
+If intents are not passed, then the library defaults to every intent being enabled except the privileged intents, currently :attr:`Intents.members` and :attr:`Intents.presences`.
+
+What intents are needed?
+--------------------------
+
+The intents that are necessary for your bot can only be dictated by yourself. Each attribute in the :class:`Intents` class documents what :ref:`events <discord-api-events>` it corresponds to and what kind of cache it enables.
+
+For example, if you want a bot that functions without spammy events like presences or typing then we could do the following:
+
+.. code-block:: python3
+
+    import discord
+    intents = Intents(typing=False, presences=False)
+
+Note that this doesn't enable :attr:`Intents.members` since it's a privileged intent.
+
+Another example showing a bot that only deals with messages and guild information:
+
+.. code-block:: python3
+
+    import discord
+    intents = discord.Intents(messages=True, guilds=True)
+    # If you also want reaction events enable the following:
+    # intents.reactions = True
+
+.. _privileged_intents:
+
+Privileged Intents
+---------------------
+
+With the API change requiring bot authors to specify intents, some intents were restricted further and require more manual steps. These intents are called **privileged intents**.
+
+A privileged intent is one that requires you to go to the developer portal and manually enable it. To enable privileged intents do the following:
+
+1. Make sure you're logged on to the `Discord website <https://discord.com>`_.
+2. Navigate to the `application page <https://discord.com/developers/applications>`_
+3. Click on the bot you want to enable privileged intents for.
+4. Navigate to the bot tab on the left side of the screen.
+
+    .. image:: /images/discord_bot_tab.png
+        :alt: The bot tab in the application page.
+
+5. Scroll down to the "Privileged Gateway Intents" section and enable the ones you want.
+
+    .. image:: /images/discord_privileged_intents.png
+        :alt: The privileged gateway intents selector.
+
+.. warning::
+
+    Enabling privileged intents when your bot is in over 100 guilds requires going through `bot verification <https://support.discord.com/hc/en-us/articles/360040720412>`_. If your bot is already verified and you would like to enable a privileged intent you must go through `discord support <https://dis.gd/contact>`_ and talk to them about it.
+
+Do I need privileged intents?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is a quick checklist to see if you need specific privileged intents.
+
+Presence Intent
++++++++++++++++++
+
+- Whether you use :attr:`Member.status` at all to track member statuses.
+- Whether you use :attr:`Member.activity` or :attr:`Member.activities` to check member's activities.
+
+Member Intent
++++++++++++++++
+
+- Whether you track member joins or member leaves, corresponds to :func:`on_member_join` and :func:`on_member_remove` events.
+- Whether you want to track member updates such as nickname or role changes.
+- Whether you want to track user updates such as usernames, avatars, discriminators, etc.
+- Whether you want to request the guild member list through :meth:`Guild.chunk` or :meth:`Guild.fetch_members`.
+- Whether you want high accuracy member cache under :attr:`Guild.members`.
+
+Member Cache
+-------------
+
+Along with intents, Discord now further restricts the ability to cache members and expects bot authors to cache as little as is necessary. However, to properly maintain a cache the :attr:`Intents.members` intent is required in order to track the members who left and properly evict them.
+
+To aid with member cache where we don't need members to be cached, the library now has a :class:`MemberCacheFlags` flag to control the member cache. The documentation page for the class goes over the specific policies that are possible.
+
+It should be noted that certain things do not need a member cache since Discord will provide full member information if possible. For example:
+
+- :func:`on_message` will have :attr:`Message.author` be a member even if cache is disabled.
+- :func:`on_voice_state_update` will have the ``member`` parameter be a member even if cache is disabled.
+- :func:`on_reaction_add` will have the ``user`` parameter be a member even if cache is disabled.
+- :func:`on_raw_reaction_add` will have :attr:`RawReactionActionEvent.member` be a member even if cache is disabled.
+- The reaction removal events do not have the member information. This is a Discord limitation.
+
+Other events that take a :class:`Member` will require the use of the member cache. If absolute accuracy over the member cache is desirable, then it is advisable to have the :attr:`Intents.members` intent enabled.