From 45127bb408e668f6e1ca4b001b857f64314243c9 Mon Sep 17 00:00:00 2001 From: Isabella Date: Wed, 3 Jan 2018 18:12:05 -0600 Subject: [PATCH] docs: improve examples (master branch) (#2209) * docs: improve examples * more improvements fix maybe this another example collectors * stuff --- src/stores/GuildMemberStore.js | 23 ++++++++++--------- src/structures/Channel.js | 4 ++-- src/structures/Guild.js | 9 ++++++-- src/structures/GuildChannel.js | 9 ++++++-- src/structures/GuildMember.js | 14 ++++++++++- src/structures/Message.js | 12 ++++++---- src/structures/interfaces/TextBasedChannel.js | 11 +++++---- 7 files changed, 56 insertions(+), 26 deletions(-) diff --git a/src/stores/GuildMemberStore.js b/src/stores/GuildMemberStore.js index ad0acbed9..692d72784 100644 --- a/src/stores/GuildMemberStore.js +++ b/src/stores/GuildMemberStore.js @@ -72,21 +72,22 @@ class GuildMemberStore extends DataStore { * @returns {Promise|Promise>} * @example * // Fetch all members from a guild - * guild.members.fetch(); + * guild.members.fetch() + * .then(console.log) + * .catch(console.error); * @example * // Fetch a single member - * guild.members.fetch('66564597481480192'); - * guild.members.fetch(user); - * guild.members.fetch({ user, cache: false }); // Fetch and don't cache + * guild.members.fetch('66564597481480192') + * .then(console.log) + * .catch(console.error); + * guild.members.fetch({ user, cache: false }) // Fetch and don't cache + * .then(console.log) + * .catch(console.error); * @example * // Fetch by query - * guild.members.fetch({ - * query: 'hydra', - * }); - * guild.members.fetch({ - * query: 'hydra', - * limit: 10, - * }); + * guild.members.fetch({ query: 'hydra' }) + * .then(console.log) + * .catch(console.error); */ fetch(options) { if (!options) return this._fetchMany(); diff --git a/src/structures/Channel.js b/src/structures/Channel.js index 833d9ef12..af17de57d 100644 --- a/src/structures/Channel.js +++ b/src/structures/Channel.js @@ -69,8 +69,8 @@ class Channel extends Base { * @example * // Delete the channel * channel.delete() - * .then() // Success - * .catch(console.error); // Log error + * then(console.log) + * .catch(console.error); */ delete() { return this.client.api.channels(this.id).delete().then(() => this); diff --git a/src/structures/Guild.js b/src/structures/Guild.js index b11548b56..c47fd74f5 100644 --- a/src/structures/Guild.js +++ b/src/structures/Guild.js @@ -514,6 +514,11 @@ class Guild extends Base { * @param {UserResolvable} [options.user] Only show entries involving this user * @param {AuditLogAction|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 = {}) { if (options.before && options.before instanceof GuildAuditLogs.Entry) options.before = options.before.id; @@ -921,8 +926,8 @@ class Guild extends Base { * @returns {Promise} * @example * // Create a new text channel - * guild.createChannel('new-general', { reason: 'My reason here.' }) - * .then(channel => console.log(`Created new channel ${channel}`)) + * guild.createChannel('new-general', { reason: 'Cool new channel' }) + * .then(console.log) * .catch(console.error); */ createChannel(name, { type, nsfw, bitrate, userLimit, parent, overwrites, reason } = {}) { diff --git a/src/structures/GuildChannel.js b/src/structures/GuildChannel.js index 25c26274b..518e12253 100644 --- a/src/structures/GuildChannel.js +++ b/src/structures/GuildChannel.js @@ -272,8 +272,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); */ async edit(data, reason) { @@ -386,6 +386,11 @@ class GuildChannel extends Channel { * @param {boolean} [options.unique=false] Create a unique invite, or use an existing one with similar settings * @param {string} [options.reason] Reason for creating this * @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({ temporary = false, maxAge = 86400, maxUses = 0, unique, reason } = {}) { return this.client.api.channels(this.id).invites.post({ data: { diff --git a/src/structures/GuildMember.js b/src/structures/GuildMember.js index f0e3952dd..8a22c0e4d 100644 --- a/src/structures/GuildMember.js +++ b/src/structures/GuildMember.js @@ -396,6 +396,16 @@ class GuildMember extends Base { * @param {Collection|RoleResolvable[]} 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); @@ -528,7 +538,9 @@ class GuildMember extends Base { * @returns {Promise} * @example * // ban a guild member - * guildMember.ban(7); + * guildMember.ban({ days: 7, reason: 'They deserved it' }) + * .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 9b86279ea..050adae9f 100644 --- a/src/structures/Message.js +++ b/src/structures/Message.js @@ -273,10 +273,8 @@ class Message extends Base { * @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`)); */ @@ -296,6 +294,12 @@ class Message extends Base { * @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 39aac0937..701d56036 100644 --- a/src/structures/interfaces/TextBasedChannel.js +++ b/src/structures/interfaces/TextBasedChannel.js @@ -195,10 +195,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`)); */ @@ -246,6 +244,11 @@ class TextBasedChannel { * 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); */ async bulkDelete(messages, filterOld = false) { if (messages instanceof Array || messages instanceof Collection) {