Nomchy/discord.js
1
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2026-03-11 00:53:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: examples & improvements

Browse Source
This commit is contained in:
Lewdcario
2018-03-01 22:50:45 -06:00
parent 9b41a6a8a6
commit 24571e465b
8 changed files with 160 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
src/structures/ClientUser.js
View File

@@ -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<Presence>}
* @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<Presence>}
* @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<Presence>}
* @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<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 = {}) {
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<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) {
const data = this.bot ? {

39
src/structures/Guild.js
View File

@@ -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<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.api.guilds(this.id).invites.get()
@@ -482,6 +492,11 @@ class Guild extends Base {
/**
* Fetches all webhooks for the guild.
* @returns {Promise<Collection<Snowflake, Webhook>>}
* @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<Guild>}
* @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) {

7
src/structures/GuildChannel.js
View File

@@ -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<GuildChannel>}
* @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({

4
src/structures/GuildMember.js
View File

@@ -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[]}
*/

16
src/structures/Message.js
View File

@@ -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<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.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) {

18
src/structures/Role.js
View File

@@ -159,8 +159,8 @@ class Role extends Base {
* @returns {Promise<Role>}
* @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<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) {

34
src/structures/Webhook.js
View File

@@ -88,10 +88,42 @@ class Webhook {
* @param {WebhookMessageOptions|MessageEmbed|MessageAttachment|MessageAttachment[]} [options={}] The options to provide
* @returns {Promise<Message|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);
*/
/* eslint-enable max-len */
async send(content, options) { // eslint-disable-line complexity

34
src/structures/interfaces/TextBasedChannel.js
View File

@@ -67,10 +67,42 @@ class TextBasedChannel {
* @param {MessageOptions|MessageEmbed|MessageAttachment|MessageAttachment[]} [options={}] Options for the message
* @returns {Promise<Message|Message[]>}
* @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)) {