docs: add jsdoc comments for event handlers (#376)

src/types/options.ts

@@ -74,42 +74,64 @@ export interface DebugArg {
 
 export interface EventHandlers {
   applicationCommandCreate?: (data: Application) => unknown;
+  /** Sent when properties about the user change. */
   botUpdate?: (user: UserPayload) => unknown;
+  /** Sent when a new guild channel is created, relevant to the current user. */
   channelCreate?: (channel: Channel) => unknown;
+  /** Sent when a channel is updated. This is not sent when the field `last_message_id` is altered. To keep track of the `last_message_id` changes, you must listen for `MESSAGE_CREATE` events. */
   channelUpdate?: (channel: Channel, cachedChannel: Channel) => unknown;
+  /** Sent when a channel relevant to the current user is deleted. */
   channelDelete?: (channel: Channel) => unknown;
   debug?: (args: DebugArg) => unknown;
   dispatchRequirements?: (data: DiscordPayload, shardID: number) => unknown;
+  /** Sent when a user is banned from a guild. */
   guildBanAdd?: (guild: Guild, user: UserPayload, member?: Member) => unknown;
+  /** Sent when a user is unbanned from a guild. */
   guildBanRemove?: (
     guild: Guild,
     user: UserPayload,
     member?: Member,
   ) => unknown;
+  /**
+   * This event can be sent in three different scenarios:
+   * 1. When a user is initially connecting, to lazily load and backfill information for all unavailable guilds sent in the `READY` event. Guilds that are unavailable due to an outage will send a `GUILD_DELETE` event.
+   * 2. When a Guild becomes available again to the client.
+   * 3. When the current user joins a new Guild.
+   */
   guildCreate?: (guild: Guild) => unknown;
   guildLoaded?: (guild: Guild) => unknown;
+  /** Sent when a guild is updated. */
   guildUpdate?: (guild: Guild, changes: GuildUpdateChange[]) => unknown;
+  /** Sent when a guild becomes or was already unavailable due to an outage, or when the user leaves or is removed from a guild. If the `unavailable` field is not set, the user was removed from the guild. */
   guildDelete?: (guild: Guild) => unknown;
+  /** Sent when a guild's emojis have been updated. */
   guildEmojisUpdate?: (
     guild: Guild,
     emojis: Emoji[],
     cachedEmojis: Emoji[],
   ) => unknown;
+  /** Sent when a new user joins a guild. */
   guildMemberAdd?: (guild: Guild, member: Member) => unknown;
+  /** Sent when a user is removed from a guild (leave/kick/ban). */
   guildMemberRemove?: (
     guild: Guild,
     user: UserPayload,
     member?: Member,
   ) => unknown;
+  /** Sent when a guild member is updated. This will also fire when the user object of a guild member changes. */
   guildMemberUpdate?: (
     guild: Guild,
     member: Member,
     cachedMember?: Member,
   ) => unknown;
   heartbeat?: () => unknown;
+  /** Sent when a user in a guild uses a Slash Command. */
   interactionCreate?: (data: InteractionCommandPayload) => unknown;
+  /** Sent when a message is created. */
   messageCreate?: (message: Message) => unknown;
+  /** Sent when a message is deleted. */
   messageDelete?: (partial: PartialMessage, message?: Message) => unknown;
+  /** Sent when a message is updated. */
   messageUpdate?: (message: Message, cachedMessage: OldMessage) => unknown;
   nicknameUpdate?: (
     guild: Guild,
@@ -117,6 +139,7 @@ export interface EventHandlers {
     nickname: string,
     oldNickname?: string,
   ) => unknown;
+  /** A user's presence is their current state on a guild. This event is sent when a user's presence or info, such as name or avatar, is updated. */
   presenceUpdate?: (
     presence: PresenceUpdatePayload,
     oldPresence?: PresenceUpdatePayload,
@@ -124,26 +147,34 @@ export interface EventHandlers {
   raw?: (data: DiscordPayload) => unknown;
   rawGateway?: (data: unknown) => unknown;
   ready?: () => unknown;
+  /** Sent when a user adds a reaction to a message. */
   reactionAdd?: (
     payload: MessageReactionUncachedPayload,
     emoji: ReactionPayload,
     userID: string,
     message?: Message,
   ) => unknown;
+  /** Sent when a user removes a reaction from a message. */
   reactionRemove?: (
     payload: MessageReactionUncachedPayload,
     emoji: ReactionPayload,
     userID: string,
     message?: Message,
   ) => unknown;
+  /** Sent when a user explicitly removes all reactions from a message. */
   reactionRemoveAll?: (data: BaseMessageReactionPayload) => unknown;
+  /** Sent when a bot removes all instances of a given emoji from the reactions of a message. */
   reactionRemoveEmoji?: (data: MessageReactionRemoveEmojiPayload) => unknown;
+  /** Sent when a guild role is created. */
   roleCreate?: (guild: Guild, role: Role) => unknown;
+  /** Sent when a guild role is deleted. */
   roleDelete?: (guild: Guild, role: Role) => unknown;
+  /** Sent when a guild role is updated. */
   roleUpdate?: (guild: Guild, role: Role, cachedRole: Role) => unknown;
   roleGained?: (guild: Guild, member: Member, roleID: string) => unknown;
   roleLost?: (guild: Guild, member: Member, roleID: string) => unknown;
   shardReady?: (shardID: number) => unknown;
+  /** Sent when a user starts typing in a channel. */
   typingStart?: (data: TypingStartPayload) => unknown;
   voiceChannelJoin?: (member: Member, channelID: string) => unknown;
   voiceChannelLeave?: (member: Member, channelID: string) => unknown;
@@ -152,10 +183,12 @@ export interface EventHandlers {
     channelID: string,
     oldChannelID: string,
   ) => unknown;
+  /** Sent when someone joins/leaves/moves voice channels. */
   voiceStateUpdate?: (
     member: Member,
     voiceState: VoiceStateUpdatePayload,
   ) => unknown;
+  /** Sent when a guild channel's webhook is created, updated, or deleted. */
   webhooksUpdate?: (channelID: string, guildID: string) => unknown;
 }