From 0101392334e48d144dda3bc1a127d1e9feb2555d Mon Sep 17 00:00:00 2001 From: SpaceEEC Date: Sat, 28 Oct 2017 19:04:03 +0200 Subject: [PATCH] Documentation improvements (#2069) * docs: fix documentation in various places All stores: resolveID returns a nullable Snowflake GuildAuditLogs: ActionType also can be ALL MessageEmbed: make files property show up in the docs ClientApplication: resetSecret and resetToken return a promise ClientManager: status is readonly Guild: features is an array of strings and ban no longer accepts a number or string Guild: ban method no longer accepts a string or number GuildMember: ^ RichPresenceAssets: small and large Image are Snowflakes, also fixed parameter documentation for small and large image url method WebhookMessageOptions: file property is no longer a thing * docs: improve GuildAuditLogs documentation Prefix types with AuditLog to avoid confusion Document GuildAuditLogs' static Targets and Actions properties and add necessary typedefs Use typdefs over primitives where possible. * fix documentation for Guild#defaultRole --- src/client/ClientManager.js | 1 + src/stores/ChannelStore.js | 2 +- src/stores/DataStore.js | 2 +- src/stores/EmojiStore.js | 2 +- src/stores/GuildChannelStore.js | 2 +- src/stores/GuildMemberStore.js | 2 +- src/stores/GuildStore.js | 2 +- src/stores/MessageStore.js | 2 +- src/stores/PresenceStore.js | 2 +- src/stores/ReactionStore.js | 2 +- src/stores/RoleStore.js | 2 +- src/stores/UserStore.js | 2 +- src/structures/ClientApplication.js | 4 +- src/structures/Guild.js | 6 +- src/structures/GuildAuditLogs.js | 93 +++++++++++++++++++++-------- src/structures/GuildMember.js | 2 +- src/structures/MessageEmbed.js | 12 ++-- src/structures/Presence.js | 14 +++-- src/structures/Webhook.js | 1 - 19 files changed, 100 insertions(+), 55 deletions(-) diff --git a/src/client/ClientManager.js b/src/client/ClientManager.js index 9e0d570d2..ad006b8fe 100644 --- a/src/client/ClientManager.js +++ b/src/client/ClientManager.js @@ -22,6 +22,7 @@ class ClientManager { /** * The status of the client + * @readonly * @type {number} */ get status() { diff --git a/src/stores/ChannelStore.js b/src/stores/ChannelStore.js index 5491b8e59..2ceee8000 100644 --- a/src/stores/ChannelStore.js +++ b/src/stores/ChannelStore.js @@ -95,7 +95,7 @@ class ChannelStore extends DataStore { * @memberof ChannelStore * @instance * @param {ChannelResolvable} channel The channel resolvable to resolve - * @returns {?string} + * @returns {?Snowflake} */ } diff --git a/src/stores/DataStore.js b/src/stores/DataStore.js index 85ce17c90..398910d50 100644 --- a/src/stores/DataStore.js +++ b/src/stores/DataStore.js @@ -37,7 +37,7 @@ class DataStore extends Collection { /** * Resolves a data entry to a instance ID. * @param {string|Instance} idOrInstance The id or instance of something in this DataStore - * @returns {?string} + * @returns {?Snowflake} */ resolveID(idOrInstance) { if (idOrInstance instanceof this.holds) return idOrInstance.id; diff --git a/src/stores/EmojiStore.js b/src/stores/EmojiStore.js index 83b4df812..035cc3d4d 100644 --- a/src/stores/EmojiStore.js +++ b/src/stores/EmojiStore.js @@ -38,7 +38,7 @@ class EmojiStore extends DataStore { /** * Resolves a EmojiResolvable to a Emoji ID string. * @param {EmojiResolvable} emoji The Emoji resolvable to identify - * @returns {?string} + * @returns {?Snowflake} */ resolveID(emoji) { if (emoji instanceof ReactionEmoji) return emoji.id; diff --git a/src/stores/GuildChannelStore.js b/src/stores/GuildChannelStore.js index 3e03c8110..0bc3e8c4e 100644 --- a/src/stores/GuildChannelStore.js +++ b/src/stores/GuildChannelStore.js @@ -42,7 +42,7 @@ class GuildChannelStore extends DataStore { * @memberof GuildChannelStore * @instance * @param {GuildChannelResolvable} channel The GuildChannel resolvable to resolve - * @returns {?string} + * @returns {?Snowflake} */ } diff --git a/src/stores/GuildMemberStore.js b/src/stores/GuildMemberStore.js index ba8cac903..ad0acbed9 100644 --- a/src/stores/GuildMemberStore.js +++ b/src/stores/GuildMemberStore.js @@ -41,7 +41,7 @@ class GuildMemberStore extends DataStore { /** * Resolves a GuildMemberResolvable to an member ID string. * @param {GuildMemberResolvable} member The user that is part of the guild - * @returns {?string} + * @returns {?Snowflake} */ resolveID(member) { const memberResolveable = super.resolveID(member); diff --git a/src/stores/GuildStore.js b/src/stores/GuildStore.js index 5e3e792a4..45e9c9cfc 100644 --- a/src/stores/GuildStore.js +++ b/src/stores/GuildStore.js @@ -33,7 +33,7 @@ class GuildStore extends DataStore { * @memberof GuildStore * @instance * @param {GuildResolvable} guild The guild resolvable to identify - * @returns {?string} + * @returns {?Snowflake} */ } diff --git a/src/stores/MessageStore.js b/src/stores/MessageStore.js index 75d01620c..cc0ff60b0 100644 --- a/src/stores/MessageStore.js +++ b/src/stores/MessageStore.js @@ -112,7 +112,7 @@ class MessageStore extends DataStore { * @memberof MessageStore * @instance * @param {MessageResolvable} message The message resolvable to resolve - * @returns {?string} + * @returns {?Snowflake} */ } diff --git a/src/stores/PresenceStore.js b/src/stores/PresenceStore.js index 1c2649712..8322c9c65 100644 --- a/src/stores/PresenceStore.js +++ b/src/stores/PresenceStore.js @@ -39,7 +39,7 @@ class PresenceStore extends DataStore { /** * Resolves a PresenceResolvable to a Presence ID string. * @param {PresenceResolvable} presence The presence resolvable to resolve - * @returns {?string} + * @returns {?Snowflake} */ resolveID(presence) { const presenceResolveable = super.resolveID(presence); diff --git a/src/stores/ReactionStore.js b/src/stores/ReactionStore.js index bcbca72ac..c11b4e176 100644 --- a/src/stores/ReactionStore.js +++ b/src/stores/ReactionStore.js @@ -38,7 +38,7 @@ class ReactionStore extends DataStore { * @memberof ReactionStore * @instance * @param {MessageReactionResolvable} role The role resolvable to resolve - * @returns {?string} + * @returns {?Snowflake} */ } diff --git a/src/stores/RoleStore.js b/src/stores/RoleStore.js index 7501cb459..bb8cd749d 100644 --- a/src/stores/RoleStore.js +++ b/src/stores/RoleStore.js @@ -38,7 +38,7 @@ class RoleStore extends DataStore { * @memberof RoleStore * @instance * @param {RoleResolvable} role The role resolvable to resolve - * @returns {?string} + * @returns {?Snowflake} */ } diff --git a/src/stores/UserStore.js b/src/stores/UserStore.js index 6ee4909a3..432a0768a 100644 --- a/src/stores/UserStore.js +++ b/src/stores/UserStore.js @@ -35,7 +35,7 @@ class UserStore extends DataStore { /** * Resolves a UserResolvable to a user ID string. * @param {UserResolvable} user The UserResolvable to identify - * @returns {?string} + * @returns {?Snowflake} */ resolveID(user) { if (user instanceof GuildMember) return user.user.id; diff --git a/src/structures/ClientApplication.js b/src/structures/ClientApplication.js index 0d2646cee..494d8c1c3 100644 --- a/src/structures/ClientApplication.js +++ b/src/structures/ClientApplication.js @@ -177,7 +177,7 @@ class ClientApplication extends Base { /** * Resets the app's secret. * This is only available when using a user account. - * @returns {ClientApplication} + * @returns {Promise} */ resetSecret() { return this.client.api.oauth2.applications[this.id].reset.post() @@ -187,7 +187,7 @@ class ClientApplication extends Base { /** * Resets the app's bot token. * This is only available when using a user account. - * @returns {ClientApplication} + * @returns {Promise} */ resetToken() { return this.client.api.oauth2.applications[this.id].bot.reset.post() diff --git a/src/structures/Guild.js b/src/structures/Guild.js index f3edd46ab..1b9463b51 100644 --- a/src/structures/Guild.js +++ b/src/structures/Guild.js @@ -115,7 +115,7 @@ class Guild extends Base { /** * An array of guild features - * @type {Object[]} + * @type {string[]} */ this.features = data.features; @@ -401,7 +401,7 @@ class Guild extends Base { } } - /* + /** * The `@everyone` role of the guild * @type {Role} * @readonly @@ -802,7 +802,7 @@ class Guild extends Base { /** * Bans a user from the guild. * @param {UserResolvable} user The user to ban - * @param {Object|number|string} [options] Ban options. If a number, the number of days to delete messages for, if a + * @param {Object} [options] Ban options. If a number, the number of days to delete messages for, if a * string, the ban reason. Supplying an object allows you to do both. * @param {number} [options.days=0] Number of days of messages to delete * @param {string} [options.reason] Reason for banning diff --git a/src/structures/GuildAuditLogs.js b/src/structures/GuildAuditLogs.js index c48da00c0..d43a48b29 100644 --- a/src/structures/GuildAuditLogs.js +++ b/src/structures/GuildAuditLogs.js @@ -2,6 +2,24 @@ const Collection = require('../util/Collection'); const Snowflake = require('../util/Snowflake'); const Webhook = require('./Webhook'); +/** + * The target type of an entry, e.g. `GUILD`. Here are the available types: + * * GUILD + * * CHANNEL + * * USER + * * ROLE + * * INVITE + * * WEBHOOK + * * EMOJI + * * MESSAGE + * @typedef {string} AuditLogTargetType + */ + +/** + * Key mirror of all available audit log targets. + * @name GuildAuditLogs.Targets + * @type {AuditLogTargetType} + */ const Targets = { ALL: 'ALL', GUILD: 'GUILD', @@ -15,6 +33,43 @@ const Targets = { UNKNOWN: 'UNKNOWN', }; +/** + * The action of an entry. Here are the available actions: + * * ALL: null + * * GUILD_UPDATE: 1 + * * CHANNEL_CREATE: 10 + * * CHANNEL_UPDATE: 11 + * * CHANNEL_DELETE: 12 + * * CHANNEL_OVERWRITE_CREATE: 13 + * * CHANNEL_OVERWRITE_UPDATE: 14 + * * CHANNEL_OVERWRITE_DELETE: 15 + * * MEMBER_KICK: 20 + * * MEMBER_PRUNE: 21 + * * MEMBER_BAN_ADD: 22 + * * MEMBER_BAN_REMOVE: 23 + * * MEMBER_UPDATE: 24 + * * MEMBER_ROLE_UPDATE: 25 + * * ROLE_CREATE: 30 + * * ROLE_UPDATE: 31 + * * ROLE_DELETE: 32 + * * INVITE_CREATE: 40 + * * INVITE_UPDATE: 41 + * * INVITE_DELETE: 42 + * * WEBHOOK_CREATE: 50 + * * WEBHOOK_UPDATE: 51 + * * WEBHOOK_DELETE: 50 + * * EMOJI_CREATE: 60 + * * EMOJI_UPDATE: 61 + * * EMOJI_DELETE: 62 + * * MESSAGE_DELETE: 72 + * @typedef {?number|string} AuditLogAction + */ + +/** + * All available actions keyed under their names to their numeric values. + * @name GuildAuditLogs.Actions + * @type {AuditLogAction} + */ const Actions = { ALL: null, GUILD_UPDATE: 1, @@ -85,20 +140,7 @@ class GuildAuditLogs { } /** - * The target type of an entry, e.g. `GUILD`. Here are the available types: - * * GUILD - * * CHANNEL - * * USER - * * ROLE - * * INVITE - * * WEBHOOK - * * EMOJI - * * MESSAGE - * @typedef {string} TargetType - */ - - /** - * The target for an audit log entry. It can be one of: + * The target of an entry. It can be one of: * * A guild * * A user * * A role @@ -106,13 +148,13 @@ class GuildAuditLogs { * * An invite * * A webhook * * An object where the keys represent either the new value or the old value - * @typedef {?Object|Guild|User|Role|Emoji|Invite|Webhook} EntryTarget + * @typedef {?Object|Guild|User|Role|Emoji|Invite|Webhook} AuditLogEntryTarget */ /** * Finds the target type from the entry action. - * @param {number} target The action target - * @returns {?string} + * @param {AuditLogAction} target The action target + * @returns {AuditLogTargetType} */ static targetType(target) { if (target < 10) return Targets.GUILD; @@ -131,13 +173,14 @@ class GuildAuditLogs { * * CREATE * * DELETE * * UPDATE - * @typedef {string} ActionType + * * ALL + * @typedef {string} AuditLogActionType */ /** * Finds the action type from the entry action. - * @param {string} action The action target - * @returns {string} + * @param {AuditLogAction} action The action target + * @returns {AuditLogActionType} */ static actionType(action) { if ([ @@ -187,19 +230,19 @@ class GuildAuditLogsEntry { const targetType = GuildAuditLogs.targetType(data.action_type); /** * The target type of this entry - * @type {TargetType} + * @type {AuditLogTargetType} */ this.targetType = targetType; /** * The action type of this entry - * @type {ActionType} + * @type {AuditLogActionType} */ this.actionType = GuildAuditLogs.actionType(data.action_type); /** - * Specific action type of this entry - * @type {string} + * Specific action type of this entry in its string presentation + * @type {AuditLogAction} */ this.action = Object.keys(Actions).find(k => Actions[k] === data.action_type); @@ -271,7 +314,7 @@ class GuildAuditLogsEntry { if (targetType === Targets.UNKNOWN) { /** * The target of this entry - * @type {EntryTarget} + * @type {AuditLogEntryTarget} */ this.target = this.changes.reduce((o, c) => { o[c.key] = c.new || c.old; diff --git a/src/structures/GuildMember.js b/src/structures/GuildMember.js index 8b83796cf..010775e29 100644 --- a/src/structures/GuildMember.js +++ b/src/structures/GuildMember.js @@ -515,7 +515,7 @@ class GuildMember extends Base { /** * Bans this guild member. - * @param {Object|number|string} [options] Ban options. If a number, the number of days to delete messages for, if a + * @param {Object} [options] Ban options. If a number, the number of days to delete messages for, if a * string, the ban reason. Supplying an object allows you to do both. * @param {number} [options.days=0] Number of days of messages to delete * @param {string} [options.reason] Reason for banning diff --git a/src/structures/MessageEmbed.js b/src/structures/MessageEmbed.js index da55d6cee..b7f430b75 100644 --- a/src/structures/MessageEmbed.js +++ b/src/structures/MessageEmbed.js @@ -132,12 +132,12 @@ class MessageEmbed { proxyIconURL: data.footer.proxyIconURL || data.footer.proxy_icon_url, } : null; - /** - * The files of this embed - * @type {?Object} - * @property {Array} files Files to attach - */ if (data.files) { + /** + * The files of this embed + * @type {?Object} + * @property {Array} files Files to attach + */ this.files = data.files.map(file => { if (file instanceof MessageAttachment) { return typeof file.file === 'string' ? file.file : Util.cloneObject(file.file); @@ -158,7 +158,7 @@ class MessageEmbed { /** * The hexadecimal version of the embed color, with a leading hash - * @type {string} + * @type {?string} * @readonly */ get hexColor() { diff --git a/src/structures/Presence.js b/src/structures/Presence.js index e788124fc..535c7d11d 100644 --- a/src/structures/Presence.js +++ b/src/structures/Presence.js @@ -160,21 +160,22 @@ class RichPresenceAssets { /** * ID of the large image asset - * @type {?string} + * @type {?Snowflake} */ this.largeImage = assets.large_image || null; /** * ID of the small image asset - * @type {?string} + * @type {?Snowflake} */ this.smallImage = assets.small_image || null; } /** * Gets the URL of the small image asset - * @param {string} format Format of the image - * @param {number} size Size of the image + * @param {Object} [options] Options for the image url + * @param {string} [options.format] Format of the image + * @param {number} [options.size] Size of the image * @returns {?string} The small image URL */ smallImageURL({ format, size } = {}) { @@ -185,8 +186,9 @@ class RichPresenceAssets { /** * Gets the URL of the large image asset - * @param {string} format Format of the image - * @param {number} size Size of the image + * @param {Object} [options] Options for the image url + * @param {string} [options.format] Format of the image + * @param {number} [options.size] Size of the image * @returns {?string} The large image URL */ largeImageURL({ format, size } = {}) { diff --git a/src/structures/Webhook.js b/src/structures/Webhook.js index a781a25a8..f1a5c6a11 100644 --- a/src/structures/Webhook.js +++ b/src/structures/Webhook.js @@ -79,7 +79,6 @@ class Webhook { * (see [here](https://discordapp.com/developers/docs/resources/channel#embed-object) for more details) * @property {boolean} [disableEveryone=this.client.options.disableEveryone] Whether or not @everyone and @here * should be replaced with plain-text - * @property {FileOptions|BufferResolvable} [file] A file to send with the message * @property {FileOptions[]|string[]} [files] Files to send with the message * @property {string|boolean} [code] Language for optional codeblock formatting to apply * @property {boolean|SplitOptions} [split=false] Whether or not the message should be split into multiple messages if