From 24571e465b1eb066a877f6fadc7f11353884deb0 Mon Sep 17 00:00:00 2001 From: Lewdcario Date: Thu, 1 Mar 2018 22:50:45 -0600 Subject: [PATCH] docs: examples & improvements --- src/structures/ClientUser.js | 37 +++++++++++++++++- src/structures/Guild.js | 39 +++++++++++++------ src/structures/GuildChannel.js | 7 +++- src/structures/GuildMember.js | 4 +- src/structures/Message.js | 16 ++++++-- src/structures/Role.js | 18 ++++----- src/structures/Webhook.js | 34 +++++++++++++++- src/structures/interfaces/TextBasedChannel.js | 34 +++++++++++++++- 8 files changed, 160 insertions(+), 29 deletions(-) diff --git a/src/structures/ClientUser.js b/src/structures/ClientUser.js index dd227c31c..900d8258e 100644 --- a/src/structures/ClientUser.js +++ b/src/structures/ClientUser.js @@ -200,6 +200,11 @@ class ClientUser extends Structures.get('User') { * Sets the full presence of the client user. * @param {PresenceData} data Data for the presence * @returns {Promise} + * @example + * // Set the client user's presence + * client.user.setPresence({ activity: { name: 'with discord.js' }, status: 'idle' }) + * .then(console.log) + * .catch(console.error); */ setPresence(data) { return this.client.presences.setClientPresence(data); @@ -218,6 +223,11 @@ class ClientUser extends Structures.get('User') { * Sets the status of the client user. * @param {PresenceStatus} status Status to change to * @returns {Promise} + * @example + * // Set the client user's status + * client.user.setStatus('idle') + * .then(console.log) + * .catch(console.error); */ setStatus(status) { return this.setPresence({ status }); @@ -230,6 +240,11 @@ class ClientUser extends Structures.get('User') { * @param {string} [options.url] Twitch stream URL * @param {ActivityType|number} [options.type] Type of the activity * @returns {Promise} + * @example + * // Set the client user's activity + * client.user.setActivity('discord.js', { type: 'WATCHING' }) + * .then(presence => console.log(`Activity set to ${presence.game.name}`)) + * .catch(console.error); */ setActivity(name, { url, type } = {}) { if (!name) return this.setPresence({ activity: null }); @@ -254,8 +269,20 @@ class ClientUser extends Structures.get('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} + * @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 = {}) { if (options.guild instanceof Guild) options.guild = options.guild.id; @@ -280,6 +307,14 @@ class ClientUser extends Structures.get('User') { * Creates a Group DM. * @param {GroupDMRecipientOptions[]} recipients The recipients * @returns {Promise} + * @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) { const data = this.bot ? { diff --git a/src/structures/Guild.js b/src/structures/Guild.js index b24bfec47..9feb8b802 100644 --- a/src/structures/Guild.js +++ b/src/structures/Guild.js @@ -466,6 +466,16 @@ class Guild extends Base { * Fetches a collection of invites to this guild. * Resolves with a collection mapping invites by their codes. * @returns {Promise>} + * @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.api.guilds(this.id).invites.get() @@ -482,6 +492,11 @@ class Guild extends Base { /** * Fetches all webhooks for the guild. * @returns {Promise>} + * @example + * // Fetch webhooks + * guild.fetchWebhooks() + * .then(webhooks => console.log(`Fetched ${webhooks.size} webhooks`)) + * .catch(console.error); */ fetchWebhooks() { return this.client.api.guilds(this.id).webhooks.get().then(data => { @@ -515,7 +530,7 @@ class Guild extends Base { * @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 = {}) { @@ -575,10 +590,12 @@ class Guild extends Base { * guild.search({ * content: 'discord.js', * before: '2016-11-17' - * }).then(res => { - * const hit = res.results[0].find(m => m.hit).content; - * console.log(`I found: **${hit}**, total results: ${res.total}`); - * }).catch(console.error); + * }) + * .then(res => { + * const hit = res.results[0].find(m => m.hit).content; + * console.log(`I found: **${hit}**, total results: ${res.total}`); + * }) + * .catch(console.error); */ search(options = {}) { return Shared.search(this, options); @@ -610,7 +627,7 @@ class Guild extends Base { * name: 'Discord Guild', * region: 'london', * }) - * .then(updated => console.log(`New guild name ${updated.name} in region ${updated.region}`)) + * .then(updated => console.log(`New guild name ${updated} in region ${updated.region}`)) * .catch(console.error); */ edit(data, reason) { @@ -653,7 +670,7 @@ class Guild extends Base { * @example * // Edit the guild name * guild.setName('Discord Guild') - * .then(updated => console.log(`Updated guild name to ${guild.name}`)) + * .then(updated => console.log(`Updated guild name to ${guild}`)) * .catch(console.error); */ setName(name, reason) { @@ -698,7 +715,7 @@ class Guild extends Base { * @example * // Edit the guild AFK channel * guild.setAFKChannel(channel) - * .then(updated => console.log(`Updated guild AFK channel to ${guild.afkChannel}`)) + * .then(updated => console.log(`Updated guild AFK channel to ${guild.afkChannel.name}`)) * .catch(console.error); */ setAFKChannel(afkChannel, reason) { @@ -713,7 +730,7 @@ class Guild extends Base { * @example * // Edit the guild system channel * guild.setSystemChannel(channel) - * .then(updated => console.log(`Updated guild system channel to ${guild.systemChannel}`)) + * .then(updated => console.log(`Updated guild system channel to ${guild.systemChannel.name}`)) * .catch(console.error); */ setSystemChannel(systemChannel, reason) { @@ -758,7 +775,7 @@ class Guild extends Base { * @example * // Edit the guild owner * guild.setOwner(guild.members.first()) - * .then(updated => console.log(`Updated the guild owner to ${updated.owner.username}`)) + * .then(updated => console.log(`Updated the guild owner to ${updated.owner.displayName}`)) * .catch(console.error); */ setOwner(owner, reason) { @@ -842,7 +859,7 @@ class Guild extends Base { * @returns {Promise} * @example * guild.setChannelPositions([{ channel: channelID, position: newChannelIndex }]) - * .then(guild => console.log(`Updated channel positions for ${guild.id}`)) + * .then(guild => console.log(`Updated channel positions for ${guild}`)) * .catch(console.error); */ setChannelPositions(channelPositions) { diff --git a/src/structures/GuildChannel.js b/src/structures/GuildChannel.js index 324b6aeda..e14e7d50d 100644 --- a/src/structures/GuildChannel.js +++ b/src/structures/GuildChannel.js @@ -354,11 +354,16 @@ class GuildChannel extends Channel { /** * Sets the category parent of this channel. - * @param {?GuildChannel|Snowflake} channel Parent channel + * @param {?CategoryChannel|Snowflake} channel Parent channel * @param {Object} [options={}] Options to pass * @param {boolean} [options.lockPermissions=true] Lock the permissions to what the parent's permissions are * @param {string} [options.reason] Reason for modifying the parent of this channel * @returns {Promise} + * @example + * // Add a parent to a channel + * message.channel.setParent('355908108431917066', { lockPermissions: false }) + * .then(channel => console.log(`New parent of ${message.channel.name}: ${channel.name}`)) + * .catch(console.error); */ setParent(channel, { lockPermissions = true, reason } = {}) { return this.edit({ diff --git a/src/structures/GuildMember.js b/src/structures/GuildMember.js index 1b988d32f..be70e315e 100644 --- a/src/structures/GuildMember.js +++ b/src/structures/GuildMember.js @@ -263,7 +263,7 @@ class GuildMember extends Base { /** * Checks if any of the member's roles have a permission. - * @param {PermissionResolvable|PermissionResolvable[]} permission Permission(s) to check for + * @param {PermissionResolvable} permission Permission(s) to check for * @param {Object} [options] Options * @param {boolean} [options.checkAdmin=true] Whether to allow the administrator permission to override * @param {boolean} [options.checkOwner=true] Whether to allow being the guild's owner to override @@ -276,7 +276,7 @@ class GuildMember extends Base { /** * Checks whether the roles of the member allows them to perform specific actions, and lists any missing permissions. - * @param {PermissionResolvable[]} permissions The permissions to check for + * @param {PermissionResolvable} permissions The permissions to check for * @param {boolean} [explicit=false] Whether to require the member to explicitly have the exact permissions * @returns {PermissionResolvable[]} */ diff --git a/src/structures/Message.js b/src/structures/Message.js index 5b9c74aa5..9736819d4 100644 --- a/src/structures/Message.js +++ b/src/structures/Message.js @@ -372,7 +372,7 @@ class Message extends Base { * @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(`Updated the content of a message to ${msg.content}`)) * .catch(console.error); */ async edit(content, options) { @@ -417,6 +417,16 @@ class Message extends Base { * Adds a reaction to the message. * @param {EmojiIdentifierResolvable} emoji The emoji to react with * @returns {Promise} + * @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.emojis.resolveIdentifier(emoji); @@ -441,7 +451,7 @@ class Message extends Base { * @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, reason } = {}) { @@ -470,7 +480,7 @@ class Message extends Base { * @example * // Reply to a message * message.reply('Hey, I\'m a reply!') - * .then(msg => console.log(`Sent a reply to ${msg.author}`)) + * .then(msg => console.log(`Sent a reply to ${msg.author.username}`)) * .catch(console.error); */ reply(content, options) { diff --git a/src/structures/Role.js b/src/structures/Role.js index 68a3c3f03..adddc5831 100644 --- a/src/structures/Role.js +++ b/src/structures/Role.js @@ -159,8 +159,8 @@ class Role extends Base { * @returns {Promise} * @example * // Edit a role - * role.edit({name: 'new role'}) - * .then(r => console.log(`Edited role ${r}`)) + * role.edit({ name: 'new role' }) + * .then(updated => console.log(`Edited role ${updated.name} name to ${updated.name}`)) * .catch(console.error); */ async edit(data, reason) { @@ -213,7 +213,7 @@ class Role extends Base { * @example * // Set the name of the role * role.setName('new role') - * .then(r => console.log(`Edited name of role ${r}`)) + * .then(updated => console.log(`Edited name of role ${role.name} to ${updated.name}`)) * .catch(console.error); */ setName(name, reason) { @@ -228,7 +228,7 @@ class Role extends Base { * @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 ${updated.color}`)) * .catch(console.error); */ setColor(color, reason) { @@ -258,7 +258,7 @@ class Role extends Base { * @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) { @@ -273,7 +273,7 @@ class Role extends Base { * @example * // Make the role mentionable * role.setMentionable(true) - * .then(r => console.log(`Role updated ${r}`)) + * .then(updated => console.log(`Role updated ${updated.name}`)) * .catch(console.error); */ setMentionable(mentionable, reason) { @@ -290,7 +290,7 @@ class Role extends Base { * @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, reason } = {}) { @@ -311,8 +311,8 @@ class Role extends Base { * @returns {Promise} * @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) { diff --git a/src/structures/Webhook.js b/src/structures/Webhook.js index ba56ebdd3..252812779 100644 --- a/src/structures/Webhook.js +++ b/src/structures/Webhook.js @@ -88,10 +88,42 @@ class Webhook { * @param {WebhookMessageOptions|MessageEmbed|MessageAttachment|MessageAttachment[]} [options={}] The options to provide * @returns {Promise} * @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); */ /* eslint-enable max-len */ async send(content, options) { // eslint-disable-line complexity diff --git a/src/structures/interfaces/TextBasedChannel.js b/src/structures/interfaces/TextBasedChannel.js index 701d56036..d67c245f3 100644 --- a/src/structures/interfaces/TextBasedChannel.js +++ b/src/structures/interfaces/TextBasedChannel.js @@ -67,10 +67,42 @@ class TextBasedChannel { * @param {MessageOptions|MessageEmbed|MessageAttachment|MessageAttachment[]} [options={}] Options for the message * @returns {Promise} * @example - * // Sends 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); */ send(content, options) { // eslint-disable-line complexity if (!options && typeof content === 'object' && !(content instanceof Array)) {