From d9262f2682b4573dd5e42b42a0ca429b08bce519 Mon Sep 17 00:00:00 2001 From: SpaceEEC Date: Thu, 10 Aug 2017 20:31:10 +0200 Subject: [PATCH] Added and fixed a bunch of docs stuff (#1767) - Fixed a common copy paste fail `the the ` in various places - Apparently I can't type Resolvable correctly, Fixed that wherever applicable - Documented GroupDMChannel#nicks so that it will be displayed on the docs - GroupDMChannel#icon is nullable - Removed empty InviteOptions typdef, as its properties are now documented in GuildChannel#createInvite - MessageMentions#channels is no longer nullable - RoleData#permissions takes a PermissionResolvable or an array of them - Webhook#avatar is nullable - Added HTTPOptions typedef and added it to ClientOptions typedef - ClientUserChannelOverride#muted is for a channel and not a guild directly --- src/client/voice/VoiceConnection.js | 2 +- src/structures/ClientUser.js | 2 +- src/structures/ClientUserGuildSettings.js | 2 +- src/structures/GroupDMChannel.js | 18 +++++++++-------- src/structures/Guild.js | 8 ++++---- src/structures/GuildChannel.js | 8 +------- src/structures/MessageMentions.js | 2 +- src/structures/Role.js | 2 +- src/structures/User.js | 2 +- src/structures/UserProfile.js | 2 +- src/structures/Webhook.js | 2 +- src/structures/interfaces/Collector.js | 2 +- src/util/Constants.js | 24 ++++++++++++++++------- 13 files changed, 41 insertions(+), 35 deletions(-) diff --git a/src/client/voice/VoiceConnection.js b/src/client/voice/VoiceConnection.js index d15c8ffbc..18c5ee084 100644 --- a/src/client/voice/VoiceConnection.js +++ b/src/client/voice/VoiceConnection.js @@ -165,7 +165,7 @@ class VoiceConnection extends EventEmitter { } /** - * Set the token and endpoint required to connect to the the voice servers. + * Set the token and endpoint required to connect to the voice servers. * @param {string} token The voice token * @param {string} endpoint The voice endpoint * @returns {void} diff --git a/src/structures/ClientUser.js b/src/structures/ClientUser.js index c26292fc1..e533e2284 100644 --- a/src/structures/ClientUser.js +++ b/src/structures/ClientUser.js @@ -346,7 +346,7 @@ class ClientUser extends User { * @property {string} [accessToken] Access token to use to add a user to the Group DM * (only available if a bot is creating the DM) * @property {string} [nick] Permanent nickname (only available if a bot is creating the DM) - * @property {string} [id] If no user resolveable is provided and you want to assign nicknames + * @property {string} [id] If no user resolvable is provided and you want to assign nicknames * you must provide user ids instead */ diff --git a/src/structures/ClientUserGuildSettings.js b/src/structures/ClientUserGuildSettings.js index dc7fd1ca6..3826c019c 100644 --- a/src/structures/ClientUserGuildSettings.js +++ b/src/structures/ClientUserGuildSettings.js @@ -8,7 +8,7 @@ const ClientUserChannelOverride = require('./ClientUserChannelOverride'); class ClientUserGuildSettings { constructor(data, client) { /** - * The client that created the instance of the the user + * The client that created the instance of the ClientUserGuildSettings * @name ClientUserGuildSettings#client * @type {Client} * @readonly diff --git a/src/structures/GroupDMChannel.js b/src/structures/GroupDMChannel.js index 9060fa932..0511cf050 100644 --- a/src/structures/GroupDMChannel.js +++ b/src/structures/GroupDMChannel.js @@ -49,7 +49,7 @@ class GroupDMChannel extends Channel { /** * A hash of this Group DM icon - * @type {string} + * @type {?string} */ this.icon = data.icon; @@ -71,11 +71,13 @@ class GroupDMChannel extends Channel { */ this.applicationID = data.application_id; - /** - * Nicknames for group members - * @type {?Collection} - */ - if (data.nicks) this.nicks = new Collection(data.nicks.map(n => [n.id, n.nick])); + if (data.nicks) { + /** + * Nicknames for group members + * @type {?Collection} + */ + this.nicks = new Collection(data.nicks.map(n => [n.id, n.nick])); + } if (!this.recipients) { /** @@ -181,7 +183,7 @@ class GroupDMChannel extends Channel { /** * Adds an user to this Group DM. * @param {Object} options Options for this method - * @param {UserResolveable} options.user User to add to this Group DM + * @param {UserResolvable} options.user User to add to this Group DM * @param {string} [options.accessToken] Access token to use to add the user to this Group DM * (only available under a bot account) * @param {string} [options.nick] Permanent nickname to give the user (only available under a bot account) @@ -198,7 +200,7 @@ class GroupDMChannel extends Channel { /** * Removes an user from this Group DM. - * @param {UserResolveable} user User to remove + * @param {UserResolvable} user User to remove * @returns {Promise} */ removeUser(user) { diff --git a/src/structures/Guild.js b/src/structures/Guild.js index 76f91a525..1b36eb2f4 100644 --- a/src/structures/Guild.js +++ b/src/structures/Guild.js @@ -25,7 +25,7 @@ const { Error, TypeError } = require('../errors'); class Guild { constructor(client, data) { /** - * The client that created the instance of the the guild + * The client that created the instance of the guild * @name Guild#client * @type {Client} * @readonly @@ -912,9 +912,9 @@ class Guild { /** * Can be used to overwrite permissions when creating a channel. * @typedef {Object} ChannelCreationOverwrites - * @property {PermissionResolveable[]|number} [allow] The permissions to allow - * @property {PermissionResolveable[]|number} [deny] The permissions to deny - * @property {RoleResolveable|UserResolvable} id ID of the group or member this overwrite is for + * @property {PermissionResolvable[]|number} [allow] The permissions to allow + * @property {PermissionResolvable[]|number} [deny] The permissions to deny + * @property {RoleResolvable|UserResolvable} id ID of the group or member this overwrite is for */ /** diff --git a/src/structures/GuildChannel.js b/src/structures/GuildChannel.js index 20356722d..71c321c1f 100644 --- a/src/structures/GuildChannel.js +++ b/src/structures/GuildChannel.js @@ -274,15 +274,9 @@ class GuildChannel extends Channel { return this.edit({ topic }, reason); } - /** - * Options given when creating a guild channel invite. - * @typedef {Object} InviteOptions - - */ - /** * Create an invite to this guild channel. - * @param {InviteOptions} [options={}] Options for the invite + * @param {Object} [options={}] Options for the invite * @param {boolean} [options.temporary=false] Whether members that joined via the invite should be automatically * kicked after 24 hours if they have not yet received a role * @param {number} [options.maxAge=86400] How long the invite should last (in seconds, 0 for forever) diff --git a/src/structures/MessageMentions.js b/src/structures/MessageMentions.js index 85fc764cb..b54787706 100644 --- a/src/structures/MessageMentions.js +++ b/src/structures/MessageMentions.js @@ -103,7 +103,7 @@ class MessageMentions { /** * Any channels that were mentioned - * @type {?Collection} + * @type {Collection} * @readonly */ get channels() { diff --git a/src/structures/Role.js b/src/structures/Role.js index c6dfb611d..797bb7121 100644 --- a/src/structures/Role.js +++ b/src/structures/Role.js @@ -186,7 +186,7 @@ class Role { * @property {ColorResolvable} [color] The color of the role, either a hex string or a base 10 number * @property {boolean} [hoist] Whether or not the role should be hoisted * @property {number} [position] The position of the role - * @property {string[]} [permissions] The permissions of the role + * @property {PermissionResolvable|PermissionResolvable[]} [permissions] The permissions of the role * @property {boolean} [mentionable] Whether or not the role should be mentionable */ diff --git a/src/structures/User.js b/src/structures/User.js index 8b0daa3fc..0a32799c5 100644 --- a/src/structures/User.js +++ b/src/structures/User.js @@ -12,7 +12,7 @@ const { Error } = require('../errors'); class User { constructor(client, data) { /** - * The client that created the instance of the the user + * The client that created the instance of the user * @name User#client * @type {Client} * @readonly diff --git a/src/structures/UserProfile.js b/src/structures/UserProfile.js index c89d62c8a..f2c9cea03 100644 --- a/src/structures/UserProfile.js +++ b/src/structures/UserProfile.js @@ -14,7 +14,7 @@ class UserProfile { this.user = user; /** - * The client that created the instance of the the UserProfile. + * The client that created the instance of the UserProfile. * @name UserProfile#client * @type {Client} * @readonly diff --git a/src/structures/Webhook.js b/src/structures/Webhook.js index ba62b2ba0..a42c3396b 100644 --- a/src/structures/Webhook.js +++ b/src/structures/Webhook.js @@ -40,7 +40,7 @@ class Webhook { /** * The avatar for the webhook - * @type {string} + * @type {?string} */ this.avatar = data.avatar; diff --git a/src/structures/interfaces/Collector.js b/src/structures/interfaces/Collector.js index 790f7e9ec..017c3797d 100644 --- a/src/structures/interfaces/Collector.js +++ b/src/structures/interfaces/Collector.js @@ -186,7 +186,7 @@ class Collector extends EventEmitter { collect() {} /** - * Handles incoming events from the the `handleDispose`. Returns null if the event should not + * Handles incoming events from the `handleDispose`. Returns null if the event should not * be disposed, or returns the key that should be removed. * @see Collector#handleDispose * @param {...*} args Any args the event listener emits diff --git a/src/util/Constants.js b/src/util/Constants.js index fddd8934f..0238ed483 100644 --- a/src/util/Constants.js +++ b/src/util/Constants.js @@ -30,6 +30,7 @@ const { Error, RangeError } = require('../errors'); * 100% certain you don't need, as many are important, but not obviously so. The safest one to disable with the * most impact is typically `TYPING_START`. * @property {WebsocketOptions} [ws] Options for the WebSocket + * @property {HTTPOptions} [http] HTTP options */ exports.DefaultOptions = { apiRequestMethod: 'sequential', @@ -63,6 +64,15 @@ exports.DefaultOptions = { }, version: 6, }, + + /** + * HTTP options + * @typedef {Object} HTTPOptions + * @property {number} [version=7] API version to use + * @property {string} [api='https://discordapp.com/api'] Base url of the API + * @property {string} [cdn='https://cdn.discordapp.com'] Base url of the CDN + * @property {string} [invite='https://discord.gg'] Base url of invites + */ http: { version: 7, api: 'https://discordapp.com/api', @@ -469,8 +479,8 @@ exports.UserSettingsMap = { explicit_content_filter: function explicitContentFilter(type) { // eslint-disable-line func-name-matching /** - * Safe direct messaging; force people's messages with images to be scanned before they are sent to you - * one of `DISABLED`, `NON_FRIENDS`, `FRIENDS_AND_NON_FRIENDS` + * Safe direct messaging; force people's messages with images to be scanned before they are sent to you. + * One of `DISABLED`, `NON_FRIENDS`, `FRIENDS_AND_NON_FRIENDS` * @name ClientUserSettings#explicitContentFilter * @type {string} */ @@ -496,8 +506,8 @@ exports.UserSettingsMap = { exports.UserGuildSettingsMap = { message_notifications: function messageNotifications(type) { // eslint-disable-line func-name-matching /** - * The type of message that should notify you - * one of `EVERYTHING`, `MENTIONS`, `NOTHING` + * The type of message that should notify you. + * One of `EVERYTHING`, `MENTIONS`, `NOTHING` * @name ClientUserGuildSettings#messageNotifications * @type {string} */ @@ -532,15 +542,15 @@ exports.UserGuildSettingsMap = { exports.UserChannelOverrideMap = { message_notifications: function messageNotifications(type) { // eslint-disable-line func-name-matching /** - * The type of message that should notify you - * one of `EVERYTHING`, `MENTIONS`, `NOTHING`, `INHERIT` + * The type of message that should notify you. + * One of `EVERYTHING`, `MENTIONS`, `NOTHING`, `INHERIT` * @name ClientUserChannelOverride#messageNotifications * @type {string} */ return exports.MessageNotificationTypes[type]; }, /** - * Whether the guild is muted or not + * Whether the channel is muted or not * @name ClientUserChannelOverride#muted * @type {boolean} */