docs: improvements

2026-03-10 16:43:31 +01:00 · 2018-02-27 10:43:20 -06:00
parent c6f92c1bc5
commit af3517594f
8 changed files with 269 additions and 65 deletions
--- a/src/structures/ClientUser.js
+++ b/src/structures/ClientUser.js
@@ -270,6 +270,10 @@ class ClientUser extends User {
   * @param {string} [options.url] Twitch stream URL
   * @param {ActivityType|number} [options.type] Type of the activity
   * @returns {Promise<Presence>}
+   * @example
+   * client.user.setActivity('YouTube', { type: 'WATCHING' })
+   *   .then(presence => console.log(`Activity set to ${presence.game ? presence.game.name : 'none'}`))
+   *   .catch(console.error);
   */
  setActivity(name, { url, type } = {}) {
    if (!name) return this.setPresence({ game: null });
@@ -293,8 +297,20 @@ class ClientUser extends User {
   * @param {number} [options.limit=25] Maximum number of mentions to retrieve
   * @param {boolean} [options.roles=true] Whether to include role mentions
   * @param {boolean} [options.everyone=true] Whether to include everyone/here mentions
-   * @param {Guild|Snowflake} [options.guild] Limit the search to a specific guild
+   * @param {GuildResolvable} [options.guild] Limit the search to a specific guild
   * @returns {Promise<Message[]>}
+   * @example
+   * // Fetch mentions
+   * client.user.fetchMentions()
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Fetch mentions from a guild
+   * client.user.fetchMentions({
+   *   guild: '222078108977594368'
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
   */
  fetchMentions(options = {}) {
    return this.client.rest.methods.fetchMentions(options);
@@ -354,6 +370,14 @@ class ClientUser extends User {
   * Creates a Group DM.
   * @param {GroupDMRecipientOptions[]} recipients The recipients
   * @returns {Promise<GroupDMChannel>}
+   * @example
+   * // Create a Group DM with a token provided from OAuth
+   * client.user.createGroupDM([{
+   *   user: '66564597481480192',
+   *   accessToken: token
+   * }])
+   *   .then(console.log)
+   *   .catch(console.error);
   */
  createGroupDM(recipients) {
    return this.client.rest.methods.createGroupDM({
--- a/src/structures/Guild.js
+++ b/src/structures/Guild.js
@@ -456,6 +456,16 @@ class Guild {
   * Fetch a collection of invites to this guild.
   * Resolves with a collection mapping invites by their codes.
   * @returns {Promise<Collection<string, Invite>>}
+   * @example
+   * // Fetch invites
+   * guild.fetchInvites()
+   *   .then(invites => console.log(`Fetched ${invites.size} invites`))
+   *   .catch(console.error);
+   * @example
+   * // Fetch invite creator by their id
+   * guild.fetchInvites()
+   *  .then(invites => console.log(invites.find(invite => invite.inviter.id === '84484653687267328')))
+   *  .then(console.error);
   */
  fetchInvites() {
    return this.client.rest.methods.getGuildInvites(this);
@@ -464,6 +474,11 @@ class Guild {
  /**
   * Fetch all webhooks for the guild.
   * @returns {Collection<Snowflake, Webhook>}
+   * @example
+   * // Fetch webhooks
+   * guild.fetchWebhooks()
+   *   .then(webhooks => console.log(`Fetched ${webhooks.size} webhooks`))
+   *   .catch(console.error);
   */
  fetchWebhooks() {
    return this.client.rest.methods.getGuildWebhooks(this);
@@ -472,6 +487,11 @@ class Guild {
  /**
   * Fetch available voice regions.
   * @returns {Collection<string, VoiceRegion>}
+   * @example
+   * // Fetch voice regions
+   * guild.fetchVoiceRegions()
+   *   .then(console.log)
+   *   .catch(console.error);
   */
  fetchVoiceRegions() {
    return this.client.rest.methods.fetchVoiceRegions(this.id);
@@ -489,7 +509,7 @@ class Guild {
   * @example
   * // Output audit log entries
   * guild.fetchAuditLogs()
-   *   .then(audit => console.log(audit.entries))
+   *   .then(audit => console.log(audit.entries.first()))
   *   .catch(console.error);
   */
  fetchAuditLogs(options) {
@@ -527,7 +547,7 @@ class Guild {
   */
  fetchMember(user, cache = true) {
    user = this.client.resolver.resolveUser(user);
-    if (!user) return Promise.reject(new Error('User is not cached. Use Client.fetchUser first.'));
+    if (!user) return Promise.reject(new Error('Invalid or uncached id provided.'));
    if (this.members.has(user.id)) return Promise.resolve(this.members.get(user.id));
    return this.client.rest.methods.getGuildMember(this, user, cache);
  }
@@ -538,12 +558,20 @@ class Guild {
   * @param {string} [query=''] Limit fetch to members with similar usernames
   * @param {number} [limit=0] Maximum number of members to request
   * @returns {Promise<Guild>}
+   * @example
+   * // Fetch guild members
+   * guild.fetchMembers()
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Fetches a maximum of 1 member with the given query
+   * guild.fetchMembers('hydrabolt', 1)
+   *   .then(console.log)
+   *   .catch(console.error);
   */
  fetchMembers(query = '', limit = 0) {
    return new Promise((resolve, reject) => {
      if (this.memberCount === this.members.size) {
-        // Uncomment in v12
-        // resolve(this.members)
        resolve(this);
        return;
      }
@@ -559,8 +587,6 @@ class Guild {
        if (guild.id !== this.id) return;
        if (this.memberCount === this.members.size || members.length < 1000) {
          this.client.removeListener(Constants.Events.GUILD_MEMBERS_CHUNK, handler);
-          // Uncomment in v12
-          // resolve(this.members)
          resolve(this);
        }
      };
@@ -578,10 +604,12 @@ class Guild {
   * guild.search({
   *   content: 'discord.js',
   *   before: '2016-11-17'
-   * }).then(res => {
-   *   const hit = res.messages[0].find(m => m.hit).content;
-   *   console.log(`I found: **${hit}**, total results: ${res.totalResults}`);
-   * }).catch(console.error);
+   * })
+   *   .then(res => {
+   *     const hit = res.messages[0].find(m => m.hit).content;
+   *     console.log(`I found: **${hit}**, total results: ${res.totalResults}`);
+   *   })
+   *   .catch(console.error);
   */
  search(options = {}) {
    return this.client.rest.methods.search(this, options);
@@ -613,7 +641,7 @@ class Guild {
   *   name: 'Discord Guild',
   *   region: 'london',
   * })
-   *   .then(updated => console.log(`New guild name ${updated.name} in region ${updated.region}`))
+   *   .then(g => console.log(`Changed guild name to ${g} and region to ${g.region}`))
   *   .catch(console.error);
   */
  edit(data, reason) {
@@ -655,7 +683,7 @@ class Guild {
   * @example
   * // Edit the guild name
   * guild.setName('Discord Guild')
-   *  .then(updated => console.log(`Updated guild name to ${guild.name}`))
+   *  .then(g => console.log(`Updated guild name to ${g}`))
   *  .catch(console.error);
   */
  setName(name, reason) {
@@ -670,7 +698,7 @@ class Guild {
   * @example
   * // Edit the guild region
   * guild.setRegion('london')
-   *  .then(updated => console.log(`Updated guild region to ${guild.region}`))
+   *  .then(g => console.log(`Updated guild region to ${g.region}`))
   *  .catch(console.error);
   */
  setRegion(region, reason) {
@@ -685,7 +713,7 @@ class Guild {
   * @example
   * // Edit the guild verification level
   * guild.setVerificationLevel(1)
-   *  .then(updated => console.log(`Updated guild verification level to ${guild.verificationLevel}`))
+   *  .then(g => console.log(`Updated guild verification level to ${g.verificationLevel}`))
   *  .catch(console.error);
   */
  setVerificationLevel(verificationLevel, reason) {
@@ -700,7 +728,7 @@ class Guild {
   * @example
   * // Edit the guild AFK channel
   * guild.setAFKChannel(channel)
-   *  .then(updated => console.log(`Updated guild AFK channel to ${guild.afkChannel}`))
+   *  .then(g => console.log(`Updated guild AFK channel to ${g.afkChannel}`))
   *  .catch(console.error);
   */
  setAFKChannel(afkChannel, reason) {
@@ -725,7 +753,7 @@ class Guild {
   * @example
   * // Edit the guild AFK channel
   * guild.setAFKTimeout(60)
-   *  .then(updated => console.log(`Updated guild AFK timeout to ${guild.afkTimeout}`))
+   *  .then(g => console.log(`Updated guild AFK timeout to ${g.afkTimeout}`))
   *  .catch(console.error);
   */
  setAFKTimeout(afkTimeout, reason) {
@@ -740,7 +768,7 @@ class Guild {
   * @example
   * // Edit the guild icon
   * guild.setIcon('./icon.png')
-   *  .then(updated => console.log('Updated the guild icon'))
+   *  .then(console.log)
   *  .catch(console.error);
   */
  setIcon(icon, reason) {
@@ -755,7 +783,7 @@ class Guild {
   * @example
   * // Edit the guild owner
   * guild.setOwner(guild.members.first())
-   *  .then(updated => console.log(`Updated the guild owner to ${updated.owner.username}`))
+   *  .then(g => console.log(`Updated the guild owner to ${g.owner.displayName}`))
   *  .catch(console.error);
   */
  setOwner(owner, reason) {
@@ -770,7 +798,7 @@ class Guild {
   * @example
   * // Edit the guild splash
   * guild.setSplash('./splash.png')
-   *  .then(updated => console.log('Updated the guild splash'))
+   *  .then(console.log)
   *  .catch(console.error);
   */
  setSplash(splash) {
@@ -823,9 +851,14 @@ class Guild {
   * If the GuildMember cannot be resolved, the User will instead be attempted to be resolved. If that also cannot
   * be resolved, the user ID will be the result.
   * @example
-   * // Ban a user by ID (or with a user/guild member object)
+   * // Ban a user by ID
   * guild.ban('some user ID')
-   *   .then(user => console.log(`Banned ${user.username || user.id || user} from ${guild.name}`))
+   *   .then(user => console.log(`Banned ${user.username || user.id || user} from ${guild}`))
+   *   .catch(console.error);
+   * @example
+   * // Ban a user by object with reason and days
+   * guild.ban(user, { days: 7, reason: 'He needed to go' })
+   *   .then(console.log)
   *   .catch(console.error);
   */
  ban(user, options = {}) {
@@ -846,7 +879,7 @@ class Guild {
   * @example
   * // Unban a user by ID (or with a user/guild member object)
   * guild.unban('some user ID')
-   *   .then(user => console.log(`Unbanned ${user.username} from ${guild.name}`))
+   *   .then(user => console.log(`Unbanned ${user.username} from ${guild}`))
   *   .catch(console.error);
   */
  unban(user, reason) {
@@ -901,7 +934,16 @@ class Guild {
   * @example
   * // Create a new text channel
   * guild.createChannel('new-general', 'text')
-   *   .then(channel => console.log(`Created new channel ${channel}`))
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Create a new category channel with permission overwrites
+   * guild.createChannel('new-category', 'category', [{
+   *   id: guild.id,
+   *   deny: ['MANAGE_MESSAGES'],
+   *   allow: ['SEND_MESSAGES']
+   * }])
+   *   .then(console.log)
   *   .catch(console.error);
   */
  createChannel(name, type, overwrites, reason) {
@@ -921,7 +963,7 @@ class Guild {
   * @returns {Promise<Guild>}
   * @example
   * guild.updateChannels([{ channel: channelID, position: newChannelIndex }])
-   *   .then(guild => console.log(`Updated channel positions for ${guild.id}`))
+   *   .then(g => console.log(`Updated channel positions for ${g}`))
   *   .catch(console.error);
   */
  setChannelPositions(channelPositions) {
@@ -929,14 +971,14 @@ class Guild {
  }

  /**
-   * Creates a new role in the guild with given information
+   * Creates a new role in the guild with given information.
   * @param {RoleData} [data] The data to update the role with
   * @param {string} [reason] Reason for creating this role
   * @returns {Promise<Role>}
   * @example
   * // Create a new role
   * guild.createRole()
-   *   .then(role => console.log(`Created role ${role}`))
+   *   .then(role => console.log(`Created new role with name ${role.name}`))
   *   .catch(console.error);
   * @example
   * // Create a new role with data
@@ -944,7 +986,7 @@ class Guild {
   *   name: 'Super Cool People',
   *   color: 'BLUE',
   * })
-   *   .then(role => console.log(`Created role ${role}`))
+   *   .then(role => console.log(`Created new role with name ${role.name} and color ${role.color}`))
   *   .catch(console.error)
   */
  createRole(data = {}, reason) {
@@ -961,12 +1003,12 @@ class Guild {
   * @example
   * // Create a new emoji from a url
   * guild.createEmoji('https://i.imgur.com/w3duR07.png', 'rip')
-   *   .then(emoji => console.log(`Created new emoji with name ${emoji.name}!`))
+   *   .then(emoji => console.log(`Created new emoji with name ${emoji.name}`))
   *   .catch(console.error);
   * @example
   * // Create a new emoji from a file on your computer
   * guild.createEmoji('./memes/banana.png', 'banana')
-   *   .then(emoji => console.log(`Created new emoji with name ${emoji.name}!`))
+   *   .then(emoji => console.log(`Created new emoji with name ${emoji.name}`))
   *   .catch(console.error);
   */
  createEmoji(attachment, name, roles, reason) {
--- a/src/structures/GuildChannel.js
+++ b/src/structures/GuildChannel.js
@@ -161,7 +161,7 @@ class GuildChannel extends Channel {
   * message.channel.overwritePermissions(message.author, {
   *   SEND_MESSAGES: false
   * })
-   *   .then(() => console.log('Done!'))
+   *   .then(updated => console.log(updated.permissionOverwrites.get(message.author.id)))
   *   .catch(console.error);
   */
  overwritePermissions(userOrRole, options, reason) {
@@ -266,6 +266,11 @@ class GuildChannel extends Channel {
   * @param {GuildChannel|SnowFlake} parent The new parent for the guild channel
   * @param {string} [reason] Reason for changing the guild channel's parent
   * @returns {Promise<GuildChannel>}
+   * @example
+   * // Sets the parent of a channel
+   * channel.setParent('174674066072928256')
+   *   .then(updated => console.log(`Set the category of ${updated.name} to ${updated.parent.name}`))
+   *   .catch(console.error);
   */
  setParent(parent, reason) {
    parent = this.client.resolver.resolveChannelID(parent);
@@ -279,8 +284,8 @@ class GuildChannel extends Channel {
   * @returns {Promise<GuildChannel>}
   * @example
   * // Set a new channel topic
-   * channel.setTopic('needs more rate limiting')
-   *   .then(newChannel => console.log(`Channel's new topic is ${newChannel.topic}`))
+   * channel.setTopic('Needs more rate limiting')
+   *   .then(updated => console.log(`Channel's new topic is ${updated.topic}`))
   *   .catch(console.error);
   */
  setTopic(topic, reason) {
@@ -315,6 +320,11 @@ class GuildChannel extends Channel {
   * @param {boolean} [withTopic=true] Whether to clone the channel with this channel's topic
   * @param {string} [reason] Reason for cloning this channel
   * @returns {Promise<GuildChannel>}
+   * @example
+   * // Clone a channel
+   * channel.clone(undefined, true, false, 'Needed a clone')
+   *   .then(clone => console.log(`Cloned ${channel.name} to make a channel called ${clone.name}`))
+   *   .catch(console.error);
   */
  clone(name = this.name, withPermissions = true, withTopic = true, reason) {
    return this.guild.createChannel(name, this.type, withPermissions ? this.permissionOverwrites : [], reason)
@@ -327,9 +337,9 @@ class GuildChannel extends Channel {
   * @returns {Promise<GuildChannel>}
   * @example
   * // Delete the channel
-   * channel.delete('making room for new channels')
-   *   .then(channel => console.log(`Deleted ${channel.name} to make room for new channels`))
-   *   .catch(console.error); // Log error
+   * channel.delete('Making room for new channels')
+   *   .then(deleted => console.log(`Deleted ${deleted.name} to make room for new channels`))
+   *   .catch(console.error);
   */
  delete(reason) {
    return this.client.rest.methods.deleteChannel(this, reason);
--- a/src/structures/GuildMember.js
+++ b/src/structures/GuildMember.js
@@ -336,7 +336,7 @@ class GuildMember {
   * The data for editing a guild member.
   * @typedef {Object} GuildMemberEditData
   * @property {string} [nick] The nickname to set for the member
-   * @property {Collection<Snowflake, Role>|Role[]|Snowflake[]} [roles] The roles or role IDs to apply
+   * @property {Collection<Snowflake, Role>|RoleResolvable[]} [roles] The roles or role IDs to apply
   * @property {boolean} [mute] Whether or not the member should be muted
   * @property {boolean} [deaf] Whether or not the member should be deafened
   * @property {ChannelResolvable} [channel] Channel to move member to (if they are connected to voice)
@@ -347,6 +347,14 @@ class GuildMember {
   * @param {GuildMemberEditData} data The data to edit the member with
   * @param {string} [reason] Reason for editing this user
   * @returns {Promise<GuildMember>}
+   * @example
+   * // Set a member's nickname and clear their roles
+   * message.member.edit({
+   *   nick: 'Cool Name',
+   *   roles: []
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
   */
  edit(data, reason) {
    return this.client.rest.methods.updateGuildMember(this, data, reason);
@@ -357,6 +365,11 @@ class GuildMember {
   * @param {boolean} mute Whether or not the member should be muted
   * @param {string} [reason] Reason for muting or unmuting
   * @returns {Promise<GuildMember>}
+   * @example
+   * // Mute a member with a reason
+   * message.member.setMute(true, 'It needed to be done')
+   *   .then(() => console.log(`Muted ${message.member.displayName}`)))
+   *   .catch(console.error);
   */
  setMute(mute, reason) {
    return this.edit({ mute }, reason);
@@ -367,6 +380,11 @@ class GuildMember {
   * @param {boolean} deaf Whether or not the member should be deafened
   * @param {string} [reason] Reason for deafening or undeafening
   * @returns {Promise<GuildMember>}
+   * @example
+   * // Deafen a member
+   * message.member.setDeaf(true)
+   *   .then(() => console.log(`Deafened ${message.member.displayName}`))
+   *   .catch(console.error);
   */
  setDeaf(deaf, reason) {
    return this.edit({ deaf }, reason);
@@ -376,6 +394,11 @@ class GuildMember {
   * Moves the guild member to the given channel.
   * @param {ChannelResolvable} channel The channel to move the member to
   * @returns {Promise<GuildMember>}
+   * @example
+   * // Moves a member to a voice channel
+   * member.setVoiceChannel('174674066072928256')
+   *   .then(() => console.log(`Moved ${member.displayName}`))
+   *   .catch(console.error);
   */
  setVoiceChannel(channel) {
    return this.edit({ channel });
@@ -383,7 +406,7 @@ class GuildMember {

  /**
   * Sets the roles applied to the member.
-   * @param {Collection<Snowflake, Role>|Role[]|Snowflake[]} roles The roles or role IDs to apply
+   * @param {Collection<Snowflake, Role>|RoleResolvable[]} roles The roles or role IDs to apply
   * @param {string} [reason] Reason for applying the roles
   * @returns {Promise<GuildMember>}
   * @example
@@ -392,9 +415,9 @@ class GuildMember {
   *   .then(console.log)
   *   .catch(console.error);
   * @example
-   * // Remove all the roles from a member
+   * // Remove all of the member's roles
   * guildMember.setRoles([])
-   *   .then(member => console.log(`Member roles is now of ${member.roles.size} size`))
+   *   .then(member => console.log(`${member.displayName} now has ${member.roles.size} roles`))
   *   .catch(console.error);
   */
  setRoles(roles, reason) {
@@ -403,9 +426,14 @@ class GuildMember {

  /**
   * Adds a single role to the member.
-   * @param {Role|Snowflake} role The role or ID of the role to add
+   * @param {RoleResolvable} role The role or ID of the role to add
   * @param {string} [reason] Reason for adding the role
   * @returns {Promise<GuildMember>}
+   * @example
+   * // Give a role to a member
+   * message.member.addRole('193654001089118208')
+   *   .then(console.log)
+   *   .catch(console.error);
   */
  addRole(role, reason) {
    if (!(role instanceof Role)) role = this.guild.roles.get(role);
@@ -415,9 +443,14 @@ class GuildMember {

  /**
   * Adds multiple roles to the member.
-   * @param {Collection<Snowflake, Role>|Role[]|Snowflake[]} roles The roles or role IDs to add
+   * @param {Collection<Snowflake, Role>|RoleResolvable[]} roles The roles or role IDs to add
   * @param {string} [reason] Reason for adding the roles
   * @returns {Promise<GuildMember>}
+   * @example
+   * // Gives a member a few roles
+   * message.member.addRoles(['193654001089118208', '369308579892690945'])
+   *   .then(console.log)
+   *   .catch(console.error);
   */
  addRoles(roles, reason) {
    let allRoles;
@@ -432,9 +465,14 @@ class GuildMember {

  /**
   * Removes a single role from the member.
-   * @param {Role|Snowflake} role The role or ID of the role to remove
+   * @param {RoleResolvable} role The role or ID of the role to remove
   * @param {string} [reason] Reason for removing the role
   * @returns {Promise<GuildMember>}
+   * @example
+   * // Remove a role from a member
+   * message.member.removeRole('193654001089118208')
+   *   .then(console.log)
+   *   .catch(console.error);
   */
  removeRole(role, reason) {
    if (!(role instanceof Role)) role = this.guild.roles.get(role);
@@ -444,9 +482,14 @@ class GuildMember {

  /**
   * Removes multiple roles from the member.
-   * @param {Collection<Snowflake, Role>|Role[]|Snowflake[]} roles The roles or role IDs to remove
+   * @param {Collection<Snowflake, Role>|RoleResolvable[]} roles The roles or role IDs to remove
   * @param {string} [reason] Reason for removing the roles
   * @returns {Promise<GuildMember>}
+   * @example
+   * // Removes a few roles from the member
+   * message.member.removeRoles(['193654001089118208', '369308579892690945'])
+   *   .then(console.log)
+   *   .catch(console.error);
   */
  removeRoles(roles, reason) {
    const allRoles = this._roles.slice();
@@ -469,6 +512,11 @@ class GuildMember {
   * @param {string} nick The nickname for the guild member
   * @param {string} [reason] Reason for setting the nickname
   * @returns {Promise<GuildMember>}
+   * @example
+   * // Update the member's nickname
+   * message.member.setNickname('Cool Name')
+   *   .then(console.log)
+   *   .catch(console.error);
   */
  setNickname(nick, reason) {
    return this.edit({ nick }, reason);
@@ -494,6 +542,11 @@ class GuildMember {
   * Kick this member from the guild.
   * @param {string} [reason] Reason for kicking user
   * @returns {Promise<GuildMember>}
+   * @example
+   * // Kick a member
+   * member.kick()
+   *   .then(() => console.log(`Kicked ${member.displayName}`))
+   *   .catch(console.error);
   */
  kick(reason) {
    return this.client.rest.methods.kickGuildMember(this.guild, this, reason);
@@ -508,8 +561,8 @@ class GuildMember {
   * @returns {Promise<GuildMember>}
   * @example
   * // Ban a guild member
-   * guildMember.ban(7)
-   *   .then(console.log)
+   * member.ban(7)
+   *   .then(() => console.log(`Banned ${member.displayName}`))
   *   .catch(console.error);
   */
  ban(options) {
--- a/src/structures/Message.js
+++ b/src/structures/Message.js
@@ -375,7 +375,7 @@ class Message {
   * @example
   * // Update the content of a message
   * message.edit('This is my new content!')
-   *   .then(msg => console.log(`Updated the content of a message from ${msg.author}`))
+   *   .then(msg => console.log(`New message content: ${msg}`))
   *   .catch(console.error);
   */
  edit(content, options) {
@@ -421,6 +421,16 @@ class Message {
   * Add a reaction to the message.
   * @param {string|Emoji|ReactionEmoji} emoji The emoji to react with
   * @returns {Promise<MessageReaction>}
+   * @example
+   * // React to a message with a unicode emoji
+   * message.react('🤔')
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // React to a message with a custom emoji
+   * message.react(message.guild.emojis.get('123456789012345678'))
+   *   .then(console.log)
+   *   .catch(console.error);
   */
  react(emoji) {
    emoji = this.client.resolver.resolveEmojiIdentifier(emoji);
@@ -444,7 +454,7 @@ class Message {
   * @example
   * // Delete a message
   * message.delete()
-   *   .then(msg => console.log(`Deleted message from ${msg.author}`))
+   *   .then(msg => console.log(`Deleted message from ${msg.author.username}`))
   *   .catch(console.error);
   */
  delete(timeout = 0) {
@@ -467,7 +477,7 @@ class Message {
   * @example
   * // Reply to a message
   * message.reply('Hey, I\'m a reply!')
-   *   .then(msg => console.log(`Sent a reply to ${msg.author}`))
+   *   .then(sent => console.log(`Sent a reply to ${sent.author.username}`))
   *   .catch(console.error);
   */
  reply(content, options) {
--- a/src/structures/Role.js
+++ b/src/structures/Role.js
@@ -205,9 +205,9 @@ class Role {
   * @param {string} [reason] The reason for editing this role
   * @returns {Promise<Role>}
   * @example
-   * // Edit a role
-   * role.edit({name: 'new role'})
-   *   .then(r => console.log(`Edited role ${r}`))
+   * // Edit name of a role
+   * role.edit({ name: 'New Name' })
+   *   .then(updated => console.log(`Edited role name from ${role.name} to ${updated.name}`))
   *   .catch(console.error);
   */
  edit(data, reason) {
@@ -221,8 +221,8 @@ class Role {
   * @returns {Promise<Role>}
   * @example
   * // Set the name of the role
-   * role.setName('new role')
-   *   .then(r => console.log(`Edited name of role ${r}`))
+   * role.setName('New Name')
+   *   .then(updated => console.log(`Edited role name from ${role.name} to ${updated.name}`))
   *   .catch(console.error);
   */
  setName(name, reason) {
@@ -237,7 +237,7 @@ class Role {
   * @example
   * // Set the color of a role
   * role.setColor('#FF0000')
-   *   .then(r => console.log(`Set color of role ${r}`))
+   *   .then(updated => console.log(`Set color of role to ${role.color}`))
   *   .catch(console.error);
   */
  setColor(color, reason) {
@@ -252,7 +252,7 @@ class Role {
   * @example
   * // Set the hoist of the role
   * role.setHoist(true)
-   *   .then(r => console.log(`Role hoisted: ${r.hoist}`))
+   *   .then(updated => console.log(`Role hoisted: ${updated.hoist}`))
   *   .catch(console.error);
   */
  setHoist(hoist, reason) {
@@ -267,7 +267,7 @@ class Role {
   * @example
   * // Set the position of the role
   * role.setPosition(1)
-   *   .then(r => console.log(`Role position: ${r.position}`))
+   *   .then(updated => console.log(`Role position: ${updated.position}`))
   *   .catch(console.error);
   */
  setPosition(position, relative) {
@@ -282,7 +282,7 @@ class Role {
   * @example
   * // Set the permissions of the role
   * role.setPermissions(['KICK_MEMBERS', 'BAN_MEMBERS'])
-   *   .then(r => console.log(`Role updated ${r}`))
+   *   .then(updated => console.log(`Updated permissions to ${updated.permissions.bitfield}`))
   *   .catch(console.error);
   */
  setPermissions(permissions, reason) {
@@ -296,8 +296,8 @@ class Role {
   * @returns {Promise<Role>}
   * @example
   * // Make the role mentionable
-   * role.setMentionable(true)
-   *   .then(r => console.log(`Role updated ${r}`))
+   * role.setMentionable(true, 'Role needs to be pinged')
+   *   .then(updated => console.log(`Role mentionable: ${updated.mentionable}`))
   *   .catch(console.error);
   */
  setMentionable(mentionable, reason) {
@@ -310,8 +310,8 @@ class Role {
   * @returns {Promise<Role>}
   * @example
   * // Delete a role
-   * role.delete()
-   *   .then(r => console.log(`Deleted role ${r}`))
+   * role.delete('The role needed to go')
+   *   .then(deleted => console.log(`Deleted role ${deleted.name}`))
   *   .catch(console.error);
   */
  delete(reason) {
--- a/src/structures/Webhook.js
+++ b/src/structures/Webhook.js
@@ -93,14 +93,46 @@ class Webhook {
  /**
   * Send a message with this webhook.
   * @param {StringResolvable} content The content to send
-   * @param {WebhookMessageOptions|Attachment|RichEmbed} [options] The options to provide
+   * @param {WebhookMessageOptions|Attachment|RichEmbed} [options] The options to provide,
   * can also be just a RichEmbed or Attachment
   * @returns {Promise<Message|Message[]|Object|Object[]>}
   * @example
-   * // Send a message
+   * // Send a basic message
   * webhook.send('hello!')
   *   .then(message => console.log(`Sent message: ${message.content}`))
   *   .catch(console.error);
+   * @example
+   * // Send a remote file
+   * webhook.send({
+   *   files: ['https://cdn.discordapp.com/icons/222078108977594368/6e1019b3179d71046e463a75915e7244.png?size=2048']
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Send a local file
+   * webhook.send({
+   *   files: [{
+   *     attachment: 'entire/path/to/file.jpg',
+   *     name: 'file.jpg'
+   *   }]
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Send an embed with a local image inside
+   * webhook.send('This is an embed', {
+   *   embeds: [{
+   *     thumbnail: {
+   *          url: 'attachment://file.jpg'
+   *       }
+   *    }],
+   *    files: [{
+   *       attachment: 'entire/path/to/file.jpg',
+   *       name: 'file.jpg'
+   *    }]
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
   */
  send(content, options) { // eslint-disable-line complexity
    if (!options && typeof content === 'object' && !(content instanceof Array)) {
--- a/src/structures/interfaces/TextBasedChannel.js
+++ b/src/structures/interfaces/TextBasedChannel.js
@@ -71,11 +71,44 @@ class TextBasedChannel {
   * can also be just a RichEmbed or Attachment
   * @returns {Promise<Message|Message[]>}
   * @example
-   * // Send a message
+   * // Send a basic message
   * channel.send('hello!')
   *   .then(message => console.log(`Sent message: ${message.content}`))
   *   .catch(console.error);
+   * @example
+   * // Send a remote file
+   * channel.send({
+   *   files: ['https://cdn.discordapp.com/icons/222078108977594368/6e1019b3179d71046e463a75915e7244.png?size=2048']
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Send a local file
+   * channel.send({
+   *   files: [{
+   *     attachment: 'entire/path/to/file.jpg',
+   *     name: 'file.jpg'
+   *   }]
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Send an embed with a local image inside
+   * channel.send('This is an embed', {
+   *   embed: {
+   *     thumbnail: {
+   *          url: 'attachment://file.jpg'
+   *       }
+   *    },
+   *    files: [{
+   *       attachment: 'entire/path/to/file.jpg',
+   *       name: 'file.jpg'
+   *    }]
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
   */
+  // eslint-disable-next-line complexity
  send(content, options) {
    if (!options && typeof content === 'object' && !(content instanceof Array)) {
      options = content;