From e7e6355cfe3ff211907fe7925442f4c952495a4d Mon Sep 17 00:00:00 2001 From: Amish Shah Date: Wed, 17 Aug 2016 16:28:31 +0100 Subject: [PATCH] work on guild docs --- docs/docs.json | 2 +- src/structures/Guild.js | 109 ++++++++++++++++++++++++++++++++++++++++ src/structures/User.js | 10 ++++ 3 files changed, 120 insertions(+), 1 deletion(-) diff --git a/docs/docs.json b/docs/docs.json index 1231865bf..cf5db4f05 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1 +1 @@ -{"meta":{"version":2},"custom":{"general":{"Getting Started":"# Welcome!\ndiscord.js is an easy-to-use and intuitive JavaScript library that wraps around the Discord API.\n"}},"json":{"classes":{"Client":{"meta":{"id":"Client","longname":"Client","name":"Client","scope":"global","kind":"class","description":"Creates a new Discord Client\n```js\nconst Discord = require(\"discord.js\");\nconst client = new Discord.Client();\n```","meta":{"lineno":18,"filename":"Client.js","path":"src/client"},"order":0},"functions":[{"id":"Client#login","longname":"Client#login","name":"login","scope":"instance","kind":"function","description":"Logs the client in. If successful, resolves with the account's token.","memberof":"Client","params":[{"type":{"names":["string"]},"description":"The email or token used for the account. If it is an email, a password _must_ be\nprovided.","name":"emailOrToken"},{"type":{"names":["string"]},"optional":true,"description":"The password for the account, only needed if an email was provided.","name":"password"}],"examples":["// log the client in using a token\nconst token = 'my token';\nclient.login(token);","// log the client in using email and password\nconst email = 'user@email.com';\nconst password = 'supersecret123';\nclient.login(email, password);"],"returns":[{"type":{"names":["Promise."]}}],"meta":{"lineno":47,"filename":"Client.js","path":"src/client"},"order":1}],"properties":[{"id":"Client#user","longname":"Client#user","name":"user","scope":"instance","kind":"member","description":"The User of the logged in Client, only available after `READY` has been fired.","memberof":"Client","params":[],"type":{"names":["ClientUser"]},"meta":{"lineno":60,"filename":"Client.js","path":"src/client"},"order":2}],"events":[]},"Message":{"meta":{"id":"Message","longname":"Message","name":"Message","scope":"global","kind":"class","description":"Represents a Message on Discord","meta":{"lineno":4,"filename":"Message.js","path":"src/structures"},"order":3},"functions":[],"properties":[],"events":[]},"TextChannel":{"meta":{"id":"TextChannel","longname":"TextChannel","name":"TextChannel","scope":"global","kind":"class","description":"Represents a Server Text Channel on Discord.","meta":{"lineno":8,"filename":"TextChannel.js","path":"src/structures"},"order":4},"functions":[],"properties":[],"events":[]},"User":{"meta":{"id":"User","longname":"User","name":"User","scope":"global","kind":"class","description":"Represents a User on Discord.","meta":{"lineno":6,"filename":"User.js","path":"src/structures"},"order":5},"functions":[{"id":"User#deleteDM","longname":"User#deleteDM","name":"deleteDM","scope":"instance","kind":"function","description":"Deletes a DM Channel (if one exists) between the Client and the User. Resolves with the Channel if successful.","memberof":"User","params":[],"returns":[{"type":{"names":["Promise."]}}],"meta":{"lineno":60,"filename":"User.js","path":"src/structures"},"order":12}],"properties":[{"id":"User#username","longname":"User#username","name":"username","scope":"instance","kind":"member","description":"The username of the User","memberof":"User","type":{"names":["String"]},"meta":{"lineno":19,"filename":"User.js","path":"src/structures"},"order":6},{"id":"User#id","longname":"User#id","name":"id","scope":"instance","kind":"member","description":"The ID of the User","memberof":"User","type":{"names":["String"]},"meta":{"lineno":24,"filename":"User.js","path":"src/structures"},"order":7},{"id":"User#discriminator","longname":"User#discriminator","name":"discriminator","scope":"instance","kind":"member","description":"A discriminator based on username for the User","memberof":"User","type":{"names":["String"]},"meta":{"lineno":29,"filename":"User.js","path":"src/structures"},"order":8},{"id":"User#avatar","longname":"User#avatar","name":"avatar","scope":"instance","kind":"member","description":"The ID of the user's avatar","memberof":"User","type":{"names":["String"]},"meta":{"lineno":34,"filename":"User.js","path":"src/structures"},"order":9},{"id":"User#bot","longname":"User#bot","name":"bot","scope":"instance","kind":"member","description":"Whether or not the User is a Bot.","memberof":"User","type":{"names":["Boolean"]},"meta":{"lineno":39,"filename":"User.js","path":"src/structures"},"order":10},{"id":"User#status","longname":"User#status","name":"status","scope":"instance","kind":"member","description":"The status of the user:\n\n* **`online`** - user is online\n* **`offline`** - user is offline\n* **`idle`** - user is AFK","memberof":"User","type":{"names":["String"]},"meta":{"lineno":48,"filename":"User.js","path":"src/structures"},"order":11}],"events":[]},"VoiceChannel":{"meta":{"id":"VoiceChannel","longname":"VoiceChannel","name":"VoiceChannel","scope":"global","kind":"class","description":"Represents a Server Voice Channel on Discord.","meta":{"lineno":7,"filename":"VoiceChannel.js","path":"src/structures"},"order":13},"functions":[],"properties":[],"events":[]}}}} \ No newline at end of file +{"meta":{"version":2},"custom":{"general":{"Getting Started":"# Welcome!\ndiscord.js is an easy-to-use and intuitive JavaScript library that wraps around the Discord API.\n"}},"json":{"classes":{"Client":{"meta":{"id":"Client","longname":"Client","name":"Client","scope":"global","kind":"class","description":"Creates a new Discord Client\n```js\nconst Discord = require(\"discord.js\");\nconst client = new Discord.Client();\n```","meta":{"lineno":18,"filename":"Client.js","path":"src/client"},"order":0},"functions":[{"id":"Client#login","longname":"Client#login","name":"login","scope":"instance","kind":"function","description":"Logs the client in. If successful, resolves with the account's token.","memberof":"Client","params":[{"type":{"names":["string"]},"description":"The email or token used for the account. If it is an email, a password _must_ be\nprovided.","name":"emailOrToken"},{"type":{"names":["string"]},"optional":true,"description":"The password for the account, only needed if an email was provided.","name":"password"}],"examples":["// log the client in using a token\nconst token = 'my token';\nclient.login(token);","// log the client in using email and password\nconst email = 'user@email.com';\nconst password = 'supersecret123';\nclient.login(email, password);"],"returns":[{"type":{"names":["Promise."]}}],"meta":{"lineno":47,"filename":"Client.js","path":"src/client"},"order":1}],"properties":[{"id":"Client#user","longname":"Client#user","name":"user","scope":"instance","kind":"member","description":"The User of the logged in Client, only available after `READY` has been fired.","memberof":"Client","params":[],"type":{"names":["ClientUser"]},"meta":{"lineno":60,"filename":"Client.js","path":"src/client"},"order":2}],"events":[]},"Guild":{"meta":{"id":"Guild","longname":"Guild","name":"Guild","scope":"global","kind":"class","meta":{"lineno":22,"filename":"Guild.js","path":"src/structures"},"order":3},"functions":[{"id":"Guild#toString","longname":"Guild#toString","name":"toString","scope":"instance","kind":"function","description":"When concatenated with a String, this automatically concatenates the Guild's name instead of the Guild object.","memberof":"Guild","params":[],"examples":["// logs: Hello from My Guild!\nconsole.log(`Hello from ${guild}!`);","// logs: Hello from My Guild!\nconsole.log(`Hello from ' + guild + '!');"],"returns":[{"type":{"names":["String"]}}],"meta":{"lineno":98,"filename":"Guild.js","path":"src/structures"},"order":9},{"id":"Guild#kick","longname":"Guild#kick","name":"kick","scope":"instance","kind":"function","description":"Tries to kick a member from the guild.","memberof":"Guild","params":[{"type":{"names":["GuildMemberResolvable"]},"description":"the member to kick","name":"member"}],"examples":["// kicks a member from a guild:\nguild.kick(message.author)\n .then(member => console.log(`Kicked ${member}`))\n .catch(error => console.log(error));"],"returns":[{"type":{"names":["Promise."]}}],"meta":{"lineno":112,"filename":"Guild.js","path":"src/structures"},"order":10},{"id":"Guild#member","longname":"Guild#member","name":"member","scope":"instance","kind":"function","description":"Returns the GuildMember form of a User object, if the User is present in the guild.","memberof":"Guild","params":[{"type":{"names":["UserResolvable"]},"description":"the user that you want to obtain the GuildMember of.","name":"user"}],"examples":["// get the guild member of a user\nconst member = guild.member(message.author);"],"returns":[{"type":{"names":["GuildMember","null"]}}],"meta":{"lineno":124,"filename":"Guild.js","path":"src/structures"},"order":11}],"properties":[{"id":"Guild#client","longname":"Guild#client","name":"client","scope":"instance","kind":"member","description":"The Client that created the instance of the the Guild.","memberof":"Guild","type":{"names":["Client"]},"meta":{"lineno":32,"filename":"Guild.js","path":"src/structures"},"order":5},{"id":"Guild#store","longname":"Guild#store","name":"store","scope":"instance","kind":"member","description":"The data store of the Guild.","memberof":"Guild","type":{"names":["GuildDataStore"]},"meta":{"lineno":38,"filename":"Guild.js","path":"src/structures"},"order":6},{"id":"Guild#available","longname":"Guild#available","name":"available","scope":"instance","kind":"member","description":"Whether the Guild is available to access. If it is not available, it indicates a server outage.","memberof":"Guild","type":{"names":["Boolean"]},"meta":{"lineno":49,"filename":"Guild.js","path":"src/structures"},"order":7},{"id":"Guild#id","longname":"Guild#id","name":"id","scope":"instance","kind":"member","description":"The Unique ID of the Guild, useful for comparisons.","memberof":"Guild","type":{"names":["String"]},"meta":{"lineno":54,"filename":"Guild.js","path":"src/structures"},"order":8},{"id":"Guild#splash","longname":"Guild#splash","name":"splash","scope":"instance","kind":"member","description":"The hash of the guild splash image, or null if no splash (VIP only)","memberof":"Guild","type":{"names":["String"]},"nullable":true,"meta":{"lineno":163,"filename":"Guild.js","path":"src/structures"},"order":12},{"id":"Guild#region","longname":"Guild#region","name":"region","scope":"instance","kind":"member","description":"The region the guild is located in","memberof":"Guild","type":{"names":["String"]},"meta":{"lineno":168,"filename":"Guild.js","path":"src/structures"},"order":13},{"id":"Guild#name","longname":"Guild#name","name":"name","scope":"instance","kind":"member","description":"The name of the guild","memberof":"Guild","type":{"names":["String"]},"meta":{"lineno":173,"filename":"Guild.js","path":"src/structures"},"order":14},{"id":"Guild#memberCount","longname":"Guild#memberCount","name":"memberCount","scope":"instance","kind":"member","description":"The amount of initial members in the guild.","memberof":"Guild","type":{"names":["Number"]},"meta":{"lineno":178,"filename":"Guild.js","path":"src/structures"},"order":15},{"id":"Guild#large","longname":"Guild#large","name":"large","scope":"instance","kind":"member","description":"Whether the guild is \"large\" (has more than 250 members)","memberof":"Guild","type":{"names":["Boolean"]},"meta":{"lineno":183,"filename":"Guild.js","path":"src/structures"},"order":16},{"id":"Guild#joinDate","longname":"Guild#joinDate","name":"joinDate","scope":"instance","kind":"member","description":"The date at which the logged-in client joined the guild.","memberof":"Guild","type":{"names":["Date"]},"meta":{"lineno":188,"filename":"Guild.js","path":"src/structures"},"order":17},{"id":"Guild#icon","longname":"Guild#icon","name":"icon","scope":"instance","kind":"member","description":"The hash of the guild icon, or null if there is no icon.","memberof":"Guild","type":{"names":["String"]},"nullable":true,"meta":{"lineno":193,"filename":"Guild.js","path":"src/structures"},"order":18},{"id":"Guild#features","longname":"Guild#features","name":"features","scope":"instance","kind":"member","description":"An array of guild features.","memberof":"Guild","type":{"names":["Array."]},"meta":{"lineno":198,"filename":"Guild.js","path":"src/structures"},"order":19},{"id":"Guild#emojis","longname":"Guild#emojis","name":"emojis","scope":"instance","kind":"member","description":"An array of guild emojis.","memberof":"Guild","type":{"names":["Array."]},"meta":{"lineno":203,"filename":"Guild.js","path":"src/structures"},"order":20},{"id":"Guild#afkTimeout","longname":"Guild#afkTimeout","name":"afkTimeout","scope":"instance","kind":"member","description":"The time in seconds before a user is counted as \"away from keyboard\".","memberof":"Guild","type":{"names":["Number"]},"nullable":true,"meta":{"lineno":208,"filename":"Guild.js","path":"src/structures"},"order":21},{"id":"Guild#afkChannelID","longname":"Guild#afkChannelID","name":"afkChannelID","scope":"instance","kind":"member","description":"The ID of the voice channel where AFK members are moved.","memberof":"Guild","type":{"names":["String"]},"nullable":true,"meta":{"lineno":213,"filename":"Guild.js","path":"src/structures"},"order":22},{"id":"Guild#embedEnabled","longname":"Guild#embedEnabled","name":"embedEnabled","scope":"instance","kind":"member","description":"Whether embedded images are enabled on this guild.","memberof":"Guild","type":{"names":["Boolean"]},"meta":{"lineno":218,"filename":"Guild.js","path":"src/structures"},"order":23},{"id":"Guild#verificationLevel","longname":"Guild#verificationLevel","name":"verificationLevel","scope":"instance","kind":"member","description":"The verification level of the guild.","memberof":"Guild","type":{"names":["Number"]},"meta":{"lineno":223,"filename":"Guild.js","path":"src/structures"},"order":24},{"id":"Guild#owner","longname":"Guild#owner","name":"owner","scope":"instance","kind":"member","description":"The owner of the guild","memberof":"Guild","type":{"names":["User"]},"meta":{"lineno":237,"filename":"Guild.js","path":"src/structures"},"order":25},{"id":"Guild#embedChannel","longname":"Guild#embedChannel","name":"embedChannel","scope":"instance","kind":"member","description":"The embed channel of the Guild.","memberof":"Guild","type":{"names":["GuildChannel"]},"meta":{"lineno":250,"filename":"Guild.js","path":"src/structures"},"order":26}],"events":[]},"Message":{"meta":{"id":"Message","longname":"Message","name":"Message","scope":"global","kind":"class","description":"Represents a Message on Discord","meta":{"lineno":4,"filename":"Message.js","path":"src/structures"},"order":27},"functions":[],"properties":[],"events":[]},"TextChannel":{"meta":{"id":"TextChannel","longname":"TextChannel","name":"TextChannel","scope":"global","kind":"class","description":"Represents a Server Text Channel on Discord.","meta":{"lineno":8,"filename":"TextChannel.js","path":"src/structures"},"order":28},"functions":[],"properties":[],"events":[]},"User":{"meta":{"id":"User","longname":"User","name":"User","scope":"global","kind":"class","description":"Represents a User on Discord.","meta":{"lineno":6,"filename":"User.js","path":"src/structures"},"order":29},"functions":[{"id":"User#deleteDM","longname":"User#deleteDM","name":"deleteDM","scope":"instance","kind":"function","description":"Deletes a DM Channel (if one exists) between the Client and the User. Resolves with the Channel if successful.","memberof":"User","params":[],"returns":[{"type":{"names":["Promise."]}}],"meta":{"lineno":64,"filename":"User.js","path":"src/structures"},"order":37},{"id":"User#equals","longname":"User#equals","name":"equals","scope":"instance","kind":"function","description":"Checks if the user is equal to another. It compares username, ID, discriminator, status and the game being played.\nIt is recommended to compare equality by using `user.id === user2.id` unless you want to compare all properties.","memberof":"User","params":[{"type":{"names":["User"]},"description":"the user to compare","name":"user"}],"returns":[{"description":"Boolean"}],"meta":{"lineno":74,"filename":"User.js","path":"src/structures"},"order":38}],"properties":[{"id":"User#username","longname":"User#username","name":"username","scope":"instance","kind":"member","description":"The username of the User","memberof":"User","type":{"names":["String"]},"meta":{"lineno":19,"filename":"User.js","path":"src/structures"},"order":30},{"id":"User#id","longname":"User#id","name":"id","scope":"instance","kind":"member","description":"The ID of the User","memberof":"User","type":{"names":["String"]},"meta":{"lineno":24,"filename":"User.js","path":"src/structures"},"order":31},{"id":"User#discriminator","longname":"User#discriminator","name":"discriminator","scope":"instance","kind":"member","description":"A discriminator based on username for the User","memberof":"User","type":{"names":["String"]},"meta":{"lineno":29,"filename":"User.js","path":"src/structures"},"order":32},{"id":"User#avatar","longname":"User#avatar","name":"avatar","scope":"instance","kind":"member","description":"The ID of the user's avatar","memberof":"User","type":{"names":["String"]},"meta":{"lineno":34,"filename":"User.js","path":"src/structures"},"order":33},{"id":"User#bot","longname":"User#bot","name":"bot","scope":"instance","kind":"member","description":"Whether or not the User is a Bot.","memberof":"User","type":{"names":["Boolean"]},"meta":{"lineno":39,"filename":"User.js","path":"src/structures"},"order":34},{"id":"User#status","longname":"User#status","name":"status","scope":"instance","kind":"member","description":"The status of the user:\n\n* **`online`** - user is online\n* **`offline`** - user is offline\n* **`idle`** - user is AFK","memberof":"User","type":{"names":["String"]},"meta":{"lineno":48,"filename":"User.js","path":"src/structures"},"order":35},{"id":"User#game","longname":"User#game","name":"game","scope":"instance","kind":"member","description":"The game that the user is playing, `null` if they aren't playing a game.","memberof":"User","type":{"names":["String"]},"meta":{"lineno":53,"filename":"User.js","path":"src/structures"},"order":36}],"events":[]},"VoiceChannel":{"meta":{"id":"VoiceChannel","longname":"VoiceChannel","name":"VoiceChannel","scope":"global","kind":"class","description":"Represents a Server Voice Channel on Discord.","meta":{"lineno":7,"filename":"VoiceChannel.js","path":"src/structures"},"order":39},"functions":[],"properties":[],"events":[]}}}} \ No newline at end of file diff --git a/src/structures/Guild.js b/src/structures/Guild.js index 596d9bf7a..8707dc94a 100644 --- a/src/structures/Guild.js +++ b/src/structures/Guild.js @@ -19,9 +19,22 @@ function arraysEqual(a, b) { return b.length === 0; } +/** + * Represents a Guild (or a Server) on Discord. + * @class Guild + */ class Guild { constructor(client, data) { + /** + * The Client that created the instance of the the Guild. + * @type {Client} + */ this.client = client; + + /** + * The data store of the Guild. + * @type {GuildDataStore} + */ this.store = new GuildDataStore(); if (!data) { @@ -29,7 +42,15 @@ class Guild { } if (data.unavailable) { + /** + * Whether the Guild is available to access. If it is not available, it indicates a server outage. + * @type {Boolean} + */ this.available = false; + /** + * The Unique ID of the Guild, useful for comparisons. + * @type {String} + */ this.id = data.id; } else { this.available = true; @@ -64,14 +85,42 @@ class Guild { this.store.remove('members', guildMember); } + /** + * When concatenated with a String, this automatically concatenates the Guild's name instead of the Guild object. + * @returns {String} + * @example + * // logs: Hello from My Guild! + * console.log(`Hello from ${guild}!`); + * @example + * // logs: Hello from My Guild! + * console.log(`Hello from ' + guild + '!'); + */ toString() { return this.name; } + /** + * Tries to kick a member from the guild. + * @param {GuildMemberResolvable} member the member to kick + * @returns {Promise} + * @example + * // kicks a member from a guild: + * guild.kick(message.author) + * .then(member => console.log(`Kicked ${member}`)) + * .catch(error => console.log(error)); + */ kick(member) { return this.member(member).kick(); } + /** + * Returns the GuildMember form of a User object, if the User is present in the guild. + * @param {UserResolvable} user the user that you want to obtain the GuildMember of. + * @returns {GuildMember|null} + * @example + * // get the guild member of a user + * const member = guild.member(message.author); + */ member(user) { return this.client.resolver.resolveGuildMember(this, user); } @@ -107,18 +156,70 @@ class Guild { setup(data) { this.id = data.id; this.available = !data.unavailable; + /** + * The hash of the guild splash image, or null if no splash (VIP only) + * @type {?String} + */ this.splash = data.splash; + /** + * The region the guild is located in + * @type {String} + */ this.region = data.region; + /** + * The name of the guild + * @type {String} + */ this.name = data.name; + /** + * The amount of initial members in the guild. + * @type {Number} + */ this.memberCount = data.member_count; + /** + * Whether the guild is "large" (has more than 250 members) + * @type {Boolean} + */ this.large = data.large; + /** + * The date at which the logged-in client joined the guild. + * @type {Date} + */ this.joinDate = new Date(data.joined_at); + /** + * The hash of the guild icon, or null if there is no icon. + * @type {?String} + */ this.icon = data.icon; + /** + * An array of guild features. + * @type {Array} + */ this.features = data.features; + /** + * An array of guild emojis. + * @type {Array} + */ this.emojis = data.emojis; + /** + * The time in seconds before a user is counted as "away from keyboard". + * @type {?Number} + */ this.afkTimeout = data.afk_timeout; + /** + * The ID of the voice channel where AFK members are moved. + * @type {?String} + */ this.afkChannelID = data.afk_channel_id; + /** + * Whether embedded images are enabled on this guild. + * @type {Boolean} + */ this.embedEnabled = data.embed_enabled; + /** + * The verification level of the guild. + * @type {Number} + */ this.verificationLevel = data.verification_level; this.features = data.features || []; @@ -129,6 +230,10 @@ class Guild { } } + /** + * The owner of the guild + * @type {User} + */ this.owner = this.store.get('members', data.owner_id); if (data.channels) { @@ -138,6 +243,10 @@ class Guild { } } + /** + * The embed channel of the Guild. + * @type {GuildChannel} + */ this.embedChannel = this.store.get('channels', data.embed_channel_id); if (data.roles) { diff --git a/src/structures/User.js b/src/structures/User.js index 823c8597d..1d8c4a497 100644 --- a/src/structures/User.js +++ b/src/structures/User.js @@ -46,6 +46,10 @@ class User { * @type {String} */ this.status = data.status || this.status || 'offline'; + /** + * The game that the user is playing, `null` if they aren't playing a game. + * @type {String} + */ this.game = data.game || this.game; } @@ -61,6 +65,12 @@ class User { return this.client.rest.methods.deleteChannel(this); } + /** + * Checks if the user is equal to another. It compares username, ID, discriminator, status and the game being played. + * It is recommended to compare equality by using `user.id === user2.id` unless you want to compare all properties. + * @param {User} user the user to compare + * @returns Boolean + */ equals(user) { let base = ( this.username === user.username &&