docs: Document most of everything so far

2 files changed, 76 insertions, 1 deletions

diff --git a/discord/client.py b/discord/client.py
index a2716b0..1100c83 100644
--- a/discord/client.py
+++ b/discord/client.py
@@ -2,6 +2,7 @@ import asyncio
 import json
 import sys
 import threading
+import warnings
 from typing import Optional, Coroutine, Any, Callable
 import websockets
 
@@ -12,20 +13,39 @@ from .user import User
 
 
 class Client:
+    """
+    Represents a Discord client (i.e. a bot).
+    You need to initialise one of these and then use `run()` with a token to login.
+    """
     _token: str
 
     @property
     async def user(self):
+        """The `discord.user.User` associated with the client."""
         data = await get(self._token, '/users/@me')
         return User(data)
 
     def __init__(self, intents: list[Intents]):
         self.gateway = None
         self.loop = asyncio.get_event_loop()
+        if Intents.MESSAGE_CONTENT in intents:
+            warnings.warn("Message Content will become a privileged intent in August 2022. You must enable it in the "
+                          "Discord developer portal.")
+        if Intents.GUILD_MEMBERS in intents or Intents.GUILD_PRESENCES in intents:
+            warnings.warn("You are using one or more privileged intent (Guild Members and/or Guild Presences). You "
+                          "must enable them in the Discord developer portal.") 
         self.code = get_number(intents)
         self.event_emitter = EventEmitter()
 
     async def connect(self, token: str, intent_code: int):
+        """
+        Connects to the Discord gateway and begins sending heartbeats.
+        This should not be called manually.
+
+        **Parameters:**
+        - token: Your bot token.
+        - intent_code: The number which represents the `discord.intents.Intents` being used.
+        """
         async with websockets.connect("wss://gateway.discord.gg/?v=10&encoding=json") as gateway:
             hello = await gateway.recv()
             self.gateway = gateway
@@ -51,6 +71,9 @@ class Client:
     async def send(self, data: dict):
         """
         Send data to the gateway.
+
+        **Parameters:**
+        - data: The data to send to the gateway.
         """
         await self.gateway.send(json.dumps(data))
     
@@ -71,6 +94,14 @@ class Client:
         pass
 
     async def heartbeat(self, gateway: websockets.WebSocketClientProtocol, interval: int):
+        """
+        Sends a heartbeat through the gateway to keep the connection active.
+        This should not be called manually.
+
+        **Parameters:**
+        - gateway: The gateway to keep open.
+        - interval: How often to send a heartbeat. This is given by the gateway in a Hello packet.
+        """
         while True:
             await asyncio.sleep(interval / 1000)
             heartbeat = {
@@ -83,6 +114,9 @@ class Client:
     def event(self, coro: Optional[Callable[..., Coroutine[Any, Any, Any]]]=None, /) -> Optional[Callable[..., Coroutine[Any, Any, Any]]]:
         """
         Registers a coroutine to be called when an event is emitted.
+
+        **Parameters:**
+        - coro: The coroutine to be registered.
         """
         if not asyncio.iscoroutinefunction(coro):
             raise TypeError('event registered must be a coroutine function')
@@ -92,6 +126,9 @@ class Client:
     def run(self, token: str):
         """
         Run the client.
+
+        **Parameters:**
+        - token: Your bot token. Do not share this with anyone!
         """
         self._token = token
         asyncio.run(self.connect(token, self.code))
diff --git a/discord/intents.py b/discord/intents.py
index f538fb6..1f2fdf1 100644
--- a/discord/intents.py
+++ b/discord/intents.py
@@ -16,24 +16,53 @@ class Intents(Enum):
     See more at: https://discord.com/developers/docs/topics/gateway#gateway-intents
     """
     GUILDS = 1
+    """Events relating to the creation, removal and modification of guilds (servers)."""
     GUILD_MEMBERS = 2
+    """
+    Events relating to the joining, leaving and modification of a guild's members.
+    Events from this intent relating to the client are sent regardless of whether the intent is enabled.
+    This is a privileged intent that must be enabled in the Discord developer portal.
+    """
     GUILD_BANS = 4
+    """Events relating to the creation and removal of a guild's bans."""
     GUILD_EMOJIS_AND_STICKERS = 8
+    """Events relating to the modification of a guild's emojis and stickers."""
     GUILD_INTEGRATIONS = 16
+    """Events relating to the creation, removal and modification of a guild's integrations."""
     GUILD_WEBHOOKS = 32
+    """Events relating to the modification of a guild's webhooks."""
     GUILD_INVITES = 64
+    """Events relating to the creation and removal of a guild's invites."""
     GUILD_VOICE_STATES = 128
+    """Events relating to the modification of a guild's voice states."""
     GUILD_PRESENCES = 256
+    """
+    Events relating to the modification of a guild's members' presences.
+    This is a privileged intent that must be enabled in the Discord developer portal.
+    """
     GUILD_MESSAGES = 512
+    """Events relating to the sending, editing and deleting of messages in a guild's channels."""
     GUILD_MESSAGE_REACTIONS = 1024
+    """Events relating to the addition and removal of reactions to messages in a guild's channels."""
     GUILD_MESSAGE_TYPING = 2048
+    """Events relating to when members start typing in a guild's channels."""
     DIRECT_MESSAGES = 4096
+    """Events relating to the sending, editing and deleting of messages in a DM channel."""
     DIRECT_MESSAGE_REACTIONS = 8192
+    """Events relating to the addition and removal of reactions to messages in a DM channel."""
     DIRECT_MESSAGE_TYPING = 16384
+    """Events relating to when users start typing in a DM channel."""
     MESSAGE_CONTENT = 32768
+    """
+    The data relating to the content of messages from message events.
+    As of August 2022, this will be a privileged intent that must be enabled in the Discord developer portal.
+    """
     GUILD_SCHEDULED_EVENTS = 65536
+    """Events relating to the scheduling, modification and cancelling of a guild's events."""
     AUTO_MODERATION_CONFIGURATION = 1048576
+    """Events relating to Automod rules."""
     AUTO_MODERATION_EXECUTION = 2097152
+    """Events relating to Automod actions."""
 
 
 def get_number(intents: list[Intents]):
@@ -41,7 +70,7 @@ def get_number(intents: list[Intents]):
     Generates the number used to tell the gateway which intents are active.
 
     **Parameters:**
-    - intents (list[Intents]): A list of active intents
+    - intents: A list of active intents
 
     **Returns:**
     - int: The number used as an argument for the gateway connection.
@@ -53,6 +82,15 @@ def get_number(intents: list[Intents]):
 
 
 def get_intents(number: int):
+    """
+    Generates a list of intents from the number used to tell the gateway which are active.
+
+    **Parameters:**
+    - number: The number which represents the intents.
+
+    **Returns:**
+    - list[`discord.intents.Intents`]: The list of intents which the number represents.
+    """
     intents = []
     while number != 0:
         for i in Intents: