From c79823002b9c05ed89d88d3b9f1b5b5bf2d15298 Mon Sep 17 00:00:00 2001 From: Isabella Date: Wed, 3 Jan 2018 18:14:36 -0600 Subject: [PATCH] docs: improve examples (#2200) * docs: improve examples another * remove conflict * some nuances * backport --- src/structures/Channel.js | 4 ++-- src/structures/Guild.js | 10 ++++++++++ src/structures/GuildChannel.js | 9 +++++++-- src/structures/GuildMember.js | 16 ++++++++++++++-- src/structures/Message.js | 12 ++++++++---- src/structures/interfaces/TextBasedChannel.js | 15 +++++++++------ 6 files changed, 50 insertions(+), 16 deletions(-) diff --git a/src/structures/Channel.js b/src/structures/Channel.js index 5cf03a608..01de2248b 100644 --- a/src/structures/Channel.js +++ b/src/structures/Channel.js @@ -58,8 +58,8 @@ class Channel { * @example * // Delete the channel * channel.delete() - * .then() // Success - * .catch(console.error); // Log error + * .then(console.log) + * .catch(console.error); */ delete() { return this.client.rest.methods.deleteChannel(this); diff --git a/src/structures/Guild.js b/src/structures/Guild.js index 8418304f2..2732613f5 100644 --- a/src/structures/Guild.js +++ b/src/structures/Guild.js @@ -486,6 +486,11 @@ class Guild { * @param {UserResolvable} [options.user] Only show entries involving this user * @param {string|number} [options.type] Only show entries involving this action type * @returns {Promise} + * @example + * // Output audit log entries + * guild.fetchAuditLogs() + * .then(audit => console.log(audit.entries)) + * .catch(console.error); */ fetchAuditLogs(options) { return this.client.rest.methods.getGuildAuditLogs(this, options); @@ -514,6 +519,11 @@ class Guild { * @param {UserResolvable} user The user to fetch the member for * @param {boolean} [cache=true] Insert the member into the members cache * @returns {Promise} + * @example + * // Fetch a guild member + * guild.fetchMember(message.author) + * .then(console.log) + * .catch(console.error); */ fetchMember(user, cache = true) { user = this.client.resolver.resolveUser(user); diff --git a/src/structures/GuildChannel.js b/src/structures/GuildChannel.js index 48a5daa63..7df4a229f 100644 --- a/src/structures/GuildChannel.js +++ b/src/structures/GuildChannel.js @@ -223,8 +223,8 @@ class GuildChannel extends Channel { * @returns {Promise} * @example * // Edit a channel - * channel.edit({name: 'new-channel'}) - * .then(c => console.log(`Edited channel ${c}`)) + * channel.edit({ name: 'new-channel' }) + * .then(console.log) * .catch(console.error); */ edit(data, reason) { @@ -298,6 +298,11 @@ class GuildChannel extends Channel { * @param {boolean} [options.unique=false] Create a unique invite, or use an existing one with similar settings * @param {string} [reason] Reason for creating the invite * @returns {Promise} + * @example + * // Create an invite to a channel + * channel.createInvite() + * .then(invite => console.log(`Created an invite with a code of ${invite.code}`)) + * .catch(console.error); */ createInvite(options = {}, reason) { return this.client.rest.methods.createChannelInvite(this, options, reason); diff --git a/src/structures/GuildMember.js b/src/structures/GuildMember.js index fdce4c0a8..77631a9e4 100644 --- a/src/structures/GuildMember.js +++ b/src/structures/GuildMember.js @@ -386,6 +386,16 @@ class GuildMember { * @param {Collection|Role[]|Snowflake[]} roles The roles or role IDs to apply * @param {string} [reason] Reason for applying the roles * @returns {Promise} + * @example + * // Set the member's roles to a single role + * guildMember.setRoles(['391156570408615936']) + * .then(console.log) + * .catch(console.error); + * @example + * // Remove all the roles from a member + * guildMember.setRoles([]) + * .then(member => console.log(`Member roles is now of ${member.roles.size} size`)) + * .catch(console.error); */ setRoles(roles, reason) { return this.edit({ roles }, reason); @@ -497,8 +507,10 @@ class GuildMember { * @param {string} [options.reason] Reason for banning * @returns {Promise} * @example - * // ban a guild member - * guildMember.ban(7); + * // Ban a guild member + * guildMember.ban(7) + * .then(console.log) + * .catch(console.error); */ ban(options) { return this.guild.ban(this, options); diff --git a/src/structures/Message.js b/src/structures/Message.js index ce83c63a9..61386f5a0 100644 --- a/src/structures/Message.js +++ b/src/structures/Message.js @@ -254,10 +254,8 @@ class Message { * @returns {ReactionCollector} * @example * // Create a reaction collector - * const collector = message.createReactionCollector( - * (reaction, user) => reaction.emoji.name === '👌' && user.id === 'someID', - * { time: 15000 } - * ); + * const filter = (reaction, user) => reaction.emoji.name === '👌' && user.id === 'someID' + * const collector = message.createReactionCollector(filter, { time: 15000 }); * collector.on('collect', r => console.log(`Collected ${r.emoji.name}`)); * collector.on('end', collected => console.log(`Collected ${collected.size} items`)); */ @@ -277,6 +275,12 @@ class Message { * @param {CollectorFilter} filter The filter function to use * @param {AwaitReactionsOptions} [options={}] Optional options to pass to the internal collector * @returns {Promise>} + * @example + * // Create a reaction collector + * const filter = (reaction, user) => reaction.emoji.name === '👌' && user.id === 'someID' + * message.awaitReactions(filter, { time: 15000 }) + * .then(collected => console.log(`Collected ${collected.size} reactions`)) + * .catch(console.error); */ awaitReactions(filter, options = {}) { return new Promise((resolve, reject) => { diff --git a/src/structures/interfaces/TextBasedChannel.js b/src/structures/interfaces/TextBasedChannel.js index bd98fb0f3..76ca49161 100644 --- a/src/structures/interfaces/TextBasedChannel.js +++ b/src/structures/interfaces/TextBasedChannel.js @@ -171,7 +171,7 @@ class TextBasedChannel { * @returns {Promise>} * @example * // Get messages - * channel.fetchMessages({limit: 10}) + * channel.fetchMessages({ limit: 10 }) * .then(messages => console.log(`Received ${messages.size} messages`)) * .catch(console.error); */ @@ -303,7 +303,7 @@ class TextBasedChannel { * It can take a few seconds for the client user to stop typing. * @param {boolean} [force=false] Whether or not to reset the call count and force the indicator to stop * @example - * // Stop typing in a channel + * // Reduce the typing count by one and stop typing if it reached 0 * channel.stopTyping(); * @example * // Force typing to fully stop in a channel @@ -357,10 +357,8 @@ class TextBasedChannel { * @returns {MessageCollector} * @example * // Create a message collector - * const collector = channel.createMessageCollector( - * m => m.content.includes('discord'), - * { time: 15000 } - * ); + * const filter = m => m.content.includes('discord'); + * const collector = channel.createMessageCollector(filter, { time: 15000 }); * collector.on('collect', m => console.log(`Collected ${m.content}`)); * collector.on('end', collected => console.log(`Collected ${collected.size} items`)); */ @@ -407,6 +405,11 @@ class TextBasedChannel { * @param {Collection|Message[]|number} messages Messages or number of messages to delete * @param {boolean} [filterOld=false] Filter messages to remove those which are older than two weeks automatically * @returns {Promise>} Deleted messages + * @example + * // Bulk delete messages + * channel.bulkDelete(5) + * .then(messages => console.log(`Bulk deleted ${messages.size} messages`)) + * .catch(console.error); */ bulkDelete(messages, filterOld = false) { if (messages instanceof Array || messages instanceof Collection) {