docs: move event docstrings to the emitting line of code

src/client/actions/ChannelCreate.js

@@ -7,16 +7,15 @@ class ChannelCreateAction extends Action {
     const existing = client.channels.has(data.id);
     const channel = client.channels.add(data);
     if (!existing && channel) {
+      /**
+       * Emitted whenever a channel is created.
+       * @event Client#channelCreate
+       * @param {DMChannel|GroupDMChannel|GuildChannel} channel The channel that was created
+       */
       client.emit(Events.CHANNEL_CREATE, channel);
     }
     return { channel };
   }
 }
 
-/**
- * Emitted whenever a channel is created.
- * @event Client#channelCreate
- * @param {GroupDMChannel|GuildChannel} channel The channel that was created
- */
-
 module.exports = ChannelCreateAction;

src/client/actions/ChannelDelete.js

@@ -14,6 +14,11 @@ class ChannelDeleteAction extends Action {
     if (channel) {
       client.channels.remove(channel.id);
       channel.deleted = true;
+      /**
+       * Emitted whenever a channel is deleted.
+       * @event Client#channelDelete
+       * @param {DMChannel|GroupDMChannel|GuildChannel} channel The channel that was deleted
+       */
       client.emit(Events.CHANNEL_DELETE, channel);
     }
 
@@ -21,10 +26,4 @@ class ChannelDeleteAction extends Action {
   }
 }
 
-/**
- * Emitted whenever a channel is deleted.
- * @event Client#channelDelete
- * @param {GroupDMChannel|GuildChannel} channel The channel that was deleted
- */
-
 module.exports = ChannelDeleteAction;

src/client/actions/GuildBanRemove.js

@@ -6,7 +6,13 @@ class GuildBanRemove extends Action {
     const client = this.client;
     const guild = client.guilds.get(data.guild_id);
     const user = client.users.add(data.user);
-    if (guild && user) client.emit(Events.GUILD_BAN_REMOVE, guild, user);
+    /**
+     * Emitted whenever a member is unbanned from a guild.
+     * @event Client#guildBanRemove
+     * @param {Guild} guild The guild that the unban occurred in
+     * @param {User} user The user that was unbanned
+     */
+    if (guild && user) client.emit(Events.GUILD_BAN_REMOVEGUILD_BAN_REMOVE, guild, user);
   }
 }
 

src/client/actions/GuildEmojiCreate.js

@@ -4,15 +4,14 @@ const { Events } = require('../../util/Constants');
 class GuildEmojiCreateAction extends Action {
   handle(guild, createdEmoji) {
     const emoji = guild.emojis.add(createdEmoji);
+    /**
+     * Emitted whenever a custom emoji is created in a guild.
+     * @event Client#emojiCreate
+     * @param {GuildEmoji} emoji The emoji that was created
+     */
     this.client.emit(Events.GUILD_EMOJI_CREATE, emoji);
     return { emoji };
   }
 }
 
-/**
- * Emitted whenever a custom emoji is created in a guild.
- * @event Client#emojiCreate
- * @param {GuildEmoji} emoji The emoji that was created
- */
-
 module.exports = GuildEmojiCreateAction;

src/client/actions/GuildEmojiDelete.js

@@ -5,15 +5,14 @@ class GuildEmojiDeleteAction extends Action {
   handle(emoji) {
     emoji.guild.emojis.remove(emoji.id);
     emoji.deleted = true;
+    /**
+     * Emitted whenever a custom emoji is deleted in a guild.
+     * @event Client#emojiDelete
+     * @param {GuildEmoji} emoji The emoji that was deleted
+     */
     this.client.emit(Events.GUILD_EMOJI_DELETE, emoji);
     return { emoji };
   }
 }
 
-/**
- * Emitted whenever a custom emoji is deleted in a guild.
- * @event Client#emojiDelete
- * @param {GuildEmoji} emoji The emoji that was deleted
- */
-
 module.exports = GuildEmojiDeleteAction;

src/client/actions/GuildEmojiUpdate.js

@@ -4,16 +4,15 @@ const { Events } = require('../../util/Constants');
 class GuildEmojiUpdateAction extends Action {
   handle(current, data) {
     const old = current._update(data);
+    /**
+     * Emitted whenever a custom emoji is updated in a guild.
+     * @event Client#emojiUpdate
+     * @param {GuildEmoji} oldEmoji The old emoji
+     * @param {GuildEmoji} newEmoji The new emoji
+     */
     this.client.emit(Events.GUILD_EMOJI_UPDATE, old, current);
     return { emoji: current };
   }
 }
 
-/**
- * Emitted whenever a custom emoji is updated in a guild.
- * @event Client#emojiUpdate
- * @param {GuildEmoji} oldEmoji The old emoji
- * @param {GuildEmoji} newEmoji The new emoji
- */
-
 module.exports = GuildEmojiUpdateAction;

src/client/actions/GuildIntegrationsUpdate.js

@@ -5,14 +5,14 @@ class GuildIntegrationsUpdate extends Action {
   handle(data) {
     const client = this.client;
     const guild = client.guilds.get(data.guild_id);
+    /**
+     * Emitted whenever a guild integration is updated
+     * @event Client#guildIntegrationsUpdate
+     * @param {Guild} guild The guild whose integrations were updated
+     */
     if (guild) client.emit(Events.GUILD_INTEGRATIONS_UPDATE, guild);
   }
 }
 
 module.exports = GuildIntegrationsUpdate;
 
-/**
- * Emitted whenever a guild integration is updated
- * @event Client#guildIntegrationsUpdate
- * @param {Guild} guild The guild whose integrations were updated
- */

src/client/actions/GuildMemberRemove.js

@@ -13,6 +13,11 @@ class GuildMemberRemoveAction extends Action {
         guild.voiceStates.delete(member.id);
         member.deleted = true;
         guild.members.remove(member.id);
+        /**
+         * Emitted whenever a member leaves a guild, or is kicked.
+         * @event Client#guildMemberRemove
+         * @param {GuildMember} member The member that has left/been kicked from the guild
+         */
         if (shard.status === Status.READY) client.emit(Events.GUILD_MEMBER_REMOVE, member);
       }
     }
@@ -20,10 +25,5 @@ class GuildMemberRemoveAction extends Action {
   }
 }
 
-/**
- * Emitted whenever a member leaves a guild, or is kicked.
- * @event Client#guildMemberRemove
- * @param {GuildMember} member The member that has left/been kicked from the guild
- */
 
 module.exports = GuildMemberRemoveAction;

src/client/actions/GuildRoleCreate.js

@@ -9,16 +9,16 @@ class GuildRoleCreate extends Action {
     if (guild) {
       const already = guild.roles.has(data.role.id);
       role = guild.roles.add(data.role);
+      /**
+       * Emitted whenever a role is created.
+       * @event Client#roleCreate
+       * @param {Role} role The role that was created
+       */
       if (!already) client.emit(Events.GUILD_ROLE_CREATE, role);
     }
     return { role };
   }
 }
 
-/**
- * Emitted whenever a role is created.
- * @event Client#roleCreate
- * @param {Role} role The role that was created
- */
 
 module.exports = GuildRoleCreate;

src/client/actions/GuildRoleDelete.js

@@ -12,6 +12,11 @@ class GuildRoleDeleteAction extends Action {
       if (role) {
         guild.roles.remove(data.role_id);
         role.deleted = true;
+        /**
+         * Emitted whenever a guild role is deleted.
+         * @event Client#roleDelete
+         * @param {Role} role The role that was deleted
+         */
         client.emit(Events.GUILD_ROLE_DELETE, role);
       }
     }
@@ -20,10 +25,5 @@ class GuildRoleDeleteAction extends Action {
   }
 }
 
-/**
- * Emitted whenever a guild role is deleted.
- * @event Client#roleDelete
- * @param {Role} role The role that was deleted
- */
 
 module.exports = GuildRoleDeleteAction;

src/client/actions/GuildRoleUpdate.js

@@ -12,6 +12,12 @@ class GuildRoleUpdateAction extends Action {
       const role = guild.roles.get(data.role.id);
       if (role) {
         old = role._update(data.role);
+        /**
+         * Emitted whenever a guild role is updated.
+         * @event Client#roleUpdate
+         * @param {Role} oldRole The role before the update
+         * @param {Role} newRole The role after the update
+         */
         client.emit(Events.GUILD_ROLE_UPDATE, old, role);
       }
 
@@ -28,11 +34,5 @@ class GuildRoleUpdateAction extends Action {
   }
 }
 
-/**
- * Emitted whenever a guild role is updated.
- * @event Client#roleUpdate
- * @param {Role} oldRole The role before the update
- * @param {Role} newRole The role after the update
- */
 
 module.exports = GuildRoleUpdateAction;

src/client/actions/GuildUpdate.js

@@ -8,6 +8,12 @@ class GuildUpdateAction extends Action {
     const guild = client.guilds.get(data.id);
     if (guild) {
       const old = guild._update(data);
+      /**
+       * Emitted whenever a guild is updated - e.g. name change.
+       * @event Client#guildUpdate
+       * @param {Guild} oldGuild The guild before the update
+       * @param {Guild} newGuild The guild after the update
+       */
       client.emit(Events.GUILD_UPDATE, old, guild);
       return {
         old,
@@ -22,11 +28,5 @@ class GuildUpdateAction extends Action {
   }
 }
 
-/**
- * Emitted whenever a guild is updated - e.g. name change.
- * @event Client#guildUpdate
- * @param {Guild} oldGuild The guild before the update
- * @param {Guild} newGuild The guild after the update
- */
 
 module.exports = GuildUpdateAction;

src/client/actions/MessageCreate.js

@@ -23,6 +23,11 @@ class MessageCreateAction extends Action {
         member.lastMessageChannelID = channel.id;
       }
 
+      /**
+       * Emitted whenever a message is created.
+       * @event Client#message
+       * @param {Message} message The created message
+       */
       client.emit(Events.MESSAGE_CREATE, message);
       return { message };
     }
@@ -31,10 +36,5 @@ class MessageCreateAction extends Action {
   }
 }
 
-/**
- * Emitted whenever a message is created.
- * @event Client#message
- * @param {Message} message The created message
- */
 
 module.exports = MessageCreateAction;

src/client/actions/MessageDelete.js

@@ -12,6 +12,11 @@ class MessageDeleteAction extends Action {
       if (message) {
         channel.messages.delete(message.id);
         message.deleted = true;
+        /**
+         * Emitted whenever a message is deleted.
+         * @event Client#messageDelete
+         * @param {Message} message The deleted message
+         */
         client.emit(Events.MESSAGE_DELETE, message);
       }
     }
@@ -20,10 +25,5 @@ class MessageDeleteAction extends Action {
   }
 }
 
-/**
- * Emitted whenever a message is deleted.
- * @event Client#messageDelete
- * @param {Message} message The deleted message
- */
 
 module.exports = MessageDeleteAction;

src/client/actions/MessageDeleteBulk.js

@@ -19,6 +19,11 @@ class MessageDeleteBulkAction extends Action {
         }
       }
 
+      /**
+       * Emitted whenever messages are deleted in bulk.
+       * @event Client#messageDeleteBulk
+       * @param {Collection<Snowflake, Message>} messages The deleted messages, mapped by their ID
+       */
       if (messages.size > 0) client.emit(Events.MESSAGE_BULK_DELETE, messages);
       return { messages };
     }
@@ -26,10 +31,5 @@ class MessageDeleteBulkAction extends Action {
   }
 }
 
-/**
- * Emitted whenever messages are deleted in bulk.
- * @event Client#messageDeleteBulk
- * @param {Collection<Snowflake, Message>} messages The deleted messages, mapped by their ID
- */
 
 module.exports = MessageDeleteBulkAction;

src/client/actions/MessageReactionAdd.js

@@ -29,11 +29,4 @@ class MessageReactionAdd extends Action {
   }
 }
 
-/**
- * Emitted whenever a reaction is added to a cached message.
- * @event Client#messageReactionAdd
- * @param {MessageReaction} messageReaction The reaction object
- * @param {User} user The user that applied the guild or reaction emoji
- */
-
 module.exports = MessageReactionAdd;

src/client/actions/MessageReactionRemove.js

@@ -24,17 +24,17 @@ class MessageReactionRemove extends Action {
     const reaction = message.reactions.get(emojiID);
     if (!reaction) return false;
     reaction._remove(user);
+    /**
+     * Emitted whenever a reaction is removed from a cached message.
+     * @event Client#messageReactionRemove
+     * @param {MessageReaction} messageReaction The reaction object
+     * @param {User} user The user whose emoji or reaction emoji was removed
+     */
     this.client.emit(Events.MESSAGE_REACTION_REMOVE, reaction, user);
 
     return { message, reaction, user };
   }
 }
 
-/**
- * Emitted whenever a reaction is removed from a cached message.
- * @event Client#messageReactionRemove
- * @param {MessageReaction} messageReaction The reaction object
- * @param {User} user The user whose emoji or reaction emoji was removed
- */
 
 module.exports = MessageReactionRemove;

src/client/actions/PresenceUpdate.js

@@ -28,6 +28,12 @@ class PresenceUpdateAction extends Action {
       const old = member._clone();
       if (member.presence) old.frozenPresence = member.presence._clone();
       guild.presences.add(data);
+      /**
+       * Emitted whenever a guild member's presence changes, or they change one of their details.
+       * @event Client#presenceUpdate
+       * @param {GuildMember} oldMember The member before the presence update
+       * @param {GuildMember} newMember The member after the presence update
+       */
       this.client.emit(Events.PRESENCE_UPDATE, old, member);
     } else {
       guild.presences.add(data);

src/client/actions/VoiceStateUpdate.js

@@ -27,16 +27,16 @@ class VoiceStateUpdate extends Action {
         client.emit('self.voiceStateUpdate', data);
       }
 
+      /**
+       * Emitted whenever a member changes voice state - e.g. joins/leaves a channel, mutes/unmutes.
+       * @event Client#voiceStateUpdate
+       * @param {?VoiceState} oldState The voice state before the update
+       * @param {VoiceState} newState The voice state after the update
+       */
       client.emit(Events.VOICE_STATE_UPDATE, oldState, newState);
     }
   }
 }
 
-/**
- * Emitted whenever a member changes voice state - e.g. joins/leaves a channel, mutes/unmutes.
- * @event Client#voiceStateUpdate
- * @param {?VoiceState} oldState The voice state before the update
- * @param {VoiceState} newState The voice state after the update
- */
 
 module.exports = VoiceStateUpdate;

src/client/actions/WebhooksUpdate.js

@@ -5,14 +5,14 @@ class WebhooksUpdate extends Action {
   handle(data) {
     const client = this.client;
     const channel = client.channels.get(data.channel_id);
+    /**
+     * Emitted whenever a guild text channel has its webhooks changed.
+     * @event Client#webhookUpdate
+     * @param {TextChannel} channel The channel that had a webhook update
+     */
     if (channel) client.emit(Events.WEBHOOKS_UPDATE, channel);
   }
 }
 
-/**
- * Emitted whenever a guild text channel has its webhooks changed.
- * @event Client#webhookUpdate
- * @param {TextChannel} channel The channel that had a webhook update
- */
 
 module.exports = WebhooksUpdate;

src/client/websocket/handlers/MESSAGE_REACTION_ADD.js

@@ -2,5 +2,11 @@ const { Events } = require('../../../util/Constants');
 
 module.exports = (client, packet) => {
   const { user, reaction } = client.actions.MessageReactionAdd.handle(packet.d);
+  /**
+   * Emitted whenever a reaction is added to a cached message.
+   * @event Client#messageReactionAdd
+   * @param {MessageReaction} messageReaction The reaction object
+   * @param {User} user The user that applied the guild or reaction emoji
+   */
   if (reaction) client.emit(Events.MESSAGE_REACTION_ADD, reaction, user);
 };