From fd21bbb7bfbfe0b51111653e140248145525d95f Mon Sep 17 00:00:00 2001
From: SpaceEEC <wermail2002-kap@yahoo.de>
Date: Tue, 27 Nov 2018 21:28:36 +0100
Subject: [PATCH] docs: move event docstrings to the emitting line of code

---
 src/client/actions/ChannelCreate.js                 | 11 +++++------
 src/client/actions/ChannelDelete.js                 | 11 +++++------
 src/client/actions/GuildBanRemove.js                |  8 +++++++-
 src/client/actions/GuildEmojiCreate.js              | 11 +++++------
 src/client/actions/GuildEmojiDelete.js              | 11 +++++------
 src/client/actions/GuildEmojiUpdate.js              | 13 ++++++-------
 src/client/actions/GuildIntegrationsUpdate.js       | 10 +++++-----
 src/client/actions/GuildMemberRemove.js             | 10 +++++-----
 src/client/actions/GuildRoleCreate.js               | 10 +++++-----
 src/client/actions/GuildRoleDelete.js               | 10 +++++-----
 src/client/actions/GuildRoleUpdate.js               | 12 ++++++------
 src/client/actions/GuildUpdate.js                   | 12 ++++++------
 src/client/actions/MessageCreate.js                 | 10 +++++-----
 src/client/actions/MessageDelete.js                 | 10 +++++-----
 src/client/actions/MessageDeleteBulk.js             | 10 +++++-----
 src/client/actions/MessageReactionAdd.js            |  7 -------
 src/client/actions/MessageReactionRemove.js         | 12 ++++++------
 src/client/actions/PresenceUpdate.js                |  6 ++++++
 src/client/actions/VoiceStateUpdate.js              | 12 ++++++------
 src/client/actions/WebhooksUpdate.js                | 10 +++++-----
 .../websocket/handlers/MESSAGE_REACTION_ADD.js      |  6 ++++++
 21 files changed, 109 insertions(+), 103 deletions(-)

diff --git a/src/client/actions/ChannelCreate.js b/src/client/actions/ChannelCreate.js
index b50d42aae..57b4e6dfd 100644
--- a/src/client/actions/ChannelCreate.js
+++ b/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;
diff --git a/src/client/actions/ChannelDelete.js b/src/client/actions/ChannelDelete.js
index f183bbc78..7f182e60c 100644
--- a/src/client/actions/ChannelDelete.js
+++ b/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;
diff --git a/src/client/actions/GuildBanRemove.js b/src/client/actions/GuildBanRemove.js
index 782b5fe2a..7d19c75ba 100644
--- a/src/client/actions/GuildBanRemove.js
+++ b/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);
   }
 }
 
diff --git a/src/client/actions/GuildEmojiCreate.js b/src/client/actions/GuildEmojiCreate.js
index 7fc955a0f..121e89ab9 100644
--- a/src/client/actions/GuildEmojiCreate.js
+++ b/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;
diff --git a/src/client/actions/GuildEmojiDelete.js b/src/client/actions/GuildEmojiDelete.js
index 82df6ec8b..7b94ff41c 100644
--- a/src/client/actions/GuildEmojiDelete.js
+++ b/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;
diff --git a/src/client/actions/GuildEmojiUpdate.js b/src/client/actions/GuildEmojiUpdate.js
index e6accf2c5..34e235a0a 100644
--- a/src/client/actions/GuildEmojiUpdate.js
+++ b/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;
diff --git a/src/client/actions/GuildIntegrationsUpdate.js b/src/client/actions/GuildIntegrationsUpdate.js
index e9c3bdbf4..8bb6eabf3 100644
--- a/src/client/actions/GuildIntegrationsUpdate.js
+++ b/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
- */
diff --git a/src/client/actions/GuildMemberRemove.js b/src/client/actions/GuildMemberRemove.js
index febeb73a0..62373e486 100644
--- a/src/client/actions/GuildMemberRemove.js
+++ b/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;
diff --git a/src/client/actions/GuildRoleCreate.js b/src/client/actions/GuildRoleCreate.js
index b4930399d..e4657213b 100644
--- a/src/client/actions/GuildRoleCreate.js
+++ b/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;
diff --git a/src/client/actions/GuildRoleDelete.js b/src/client/actions/GuildRoleDelete.js
index ce6bcaedf..0cecc8efe 100644
--- a/src/client/actions/GuildRoleDelete.js
+++ b/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;
diff --git a/src/client/actions/GuildRoleUpdate.js b/src/client/actions/GuildRoleUpdate.js
index 2437264fa..c2e082c70 100644
--- a/src/client/actions/GuildRoleUpdate.js
+++ b/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;
diff --git a/src/client/actions/GuildUpdate.js b/src/client/actions/GuildUpdate.js
index b828bb103..ac592d277 100644
--- a/src/client/actions/GuildUpdate.js
+++ b/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;
diff --git a/src/client/actions/MessageCreate.js b/src/client/actions/MessageCreate.js
index 9308aedb1..e34eabc2b 100644
--- a/src/client/actions/MessageCreate.js
+++ b/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;
diff --git a/src/client/actions/MessageDelete.js b/src/client/actions/MessageDelete.js
index c31c39cb4..cbe555e86 100644
--- a/src/client/actions/MessageDelete.js
+++ b/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;
diff --git a/src/client/actions/MessageDeleteBulk.js b/src/client/actions/MessageDeleteBulk.js
index e12eaa73a..ac8d9b399 100644
--- a/src/client/actions/MessageDeleteBulk.js
+++ b/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;
diff --git a/src/client/actions/MessageReactionAdd.js b/src/client/actions/MessageReactionAdd.js
index 0708d3380..06b146df6 100644
--- a/src/client/actions/MessageReactionAdd.js
+++ b/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;
diff --git a/src/client/actions/MessageReactionRemove.js b/src/client/actions/MessageReactionRemove.js
index 63e349f7d..af76c4fd9 100644
--- a/src/client/actions/MessageReactionRemove.js
+++ b/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;
diff --git a/src/client/actions/PresenceUpdate.js b/src/client/actions/PresenceUpdate.js
index 53b18c80a..538e0e8af 100644
--- a/src/client/actions/PresenceUpdate.js
+++ b/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);
diff --git a/src/client/actions/VoiceStateUpdate.js b/src/client/actions/VoiceStateUpdate.js
index 0eb9c5a57..80e120cb2 100644
--- a/src/client/actions/VoiceStateUpdate.js
+++ b/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;
diff --git a/src/client/actions/WebhooksUpdate.js b/src/client/actions/WebhooksUpdate.js
index 5ffc41a40..08ec838f1 100644
--- a/src/client/actions/WebhooksUpdate.js
+++ b/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;
diff --git a/src/client/websocket/handlers/MESSAGE_REACTION_ADD.js b/src/client/websocket/handlers/MESSAGE_REACTION_ADD.js
index d81762124..e2ac2c07a 100644
--- a/src/client/websocket/handlers/MESSAGE_REACTION_ADD.js
+++ b/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);
 };