docs: general cleanup and improvements (#6299)

Co-authored-by: DaStormer <40336269+DaStormer@users.noreply.github.com> Co-authored-by: Sugden <28943913+NotSugden@users.noreply.github.com> Co-authored-by: SpaceEEC <spaceeec@yahoo.com>
2026-03-12 17:43:30 +01:00 · 2021-08-05 20:34:06 +01:00
parent 4241febe24
commit b4afcf8236
39 changed files with 203 additions and 136 deletions
--- a/src/util/ApplicationFlags.js
+++ b/src/util/ApplicationFlags.js
@@ -23,9 +23,6 @@ class ApplicationFlags extends BitField {}

 /**
 * Numeric application flags. All available properties:
- * * `MANAGED_EMOJI`
- * * `GROUP_DM_CREATE`
- * * `RPC_HAS_CONNECTED`
 * * `GATEWAY_PRESENCE`
 * * `GATEWAY_PRESENCE_LIMITED`
 * * `GATEWAY_GUILD_MEMBERS`
@@ -33,11 +30,9 @@ class ApplicationFlags extends BitField {}
 * * `VERIFICATION_PENDING_GUILD_LIMIT`
 * * `EMBEDDED`
 * @type {Object}
+ * @see {@link https://discord.com/developers/docs/resources/application#application-object-application-flags}
 */
 ApplicationFlags.FLAGS = {
-  MANAGED_EMOJI: 1 << 2,
-  GROUP_DM_CREATE: 1 << 4,
-  RPC_HAS_CONNECTED: 1 << 11,
  GATEWAY_PRESENCE: 1 << 12,
  GATEWAY_PRESENCE_LIMITED: 1 << 13,
  GATEWAY_GUILD_MEMBERS: 1 << 14,
--- a/src/util/BitField.js
+++ b/src/util/BitField.js
@@ -57,7 +57,7 @@ class BitField {

  /**
   * Freezes these bits, making them immutable.
-   * @returns {Readonly<BitField>} These bits
+   * @returns {Readonly<BitField>}
   */
  freeze() {
    return Object.freeze(this);
--- a/src/util/Constants.js
+++ b/src/util/Constants.js
@@ -34,15 +34,15 @@ function makeImageUrl(root, { format = 'webp', size } = {}) {
 /**
 * Options for static Image URLs.
 * @typedef {Object} StaticImageURLOptions
- * @property {string} [format] One of `webp`, `png`, `jpg`, `jpeg`, `gif`. If no format is provided,
- * defaults to `webp`
+ * @property {string} [format='webp'] One of `webp`, `png`, `jpg`, `jpeg`.
 * @property {number} [size] One of `16`, `32`, `64`, `128`, `256`, `512`, `1024`, `2048`, `4096`
 */

+// https://discord.com/developers/docs/reference#image-formatting-cdn-endpoints
 exports.Endpoints = {
  CDN(root) {
    return {
-      Emoji: (emojiId, format = 'png') => `${root}/emojis/${emojiId}.${format}`,
+      Emoji: (emojiId, format = 'webp') => `${root}/emojis/${emojiId}.${format}`,
      Asset: name => `${root}/assets/${name}`,
      DefaultAvatar: discriminator => `${root}/embed/avatars/${discriminator}.png`,
      Avatar: (userId, hash, format = 'webp', size, dynamic = false) => {
@@ -262,6 +262,7 @@ exports.PartialTypes = keyMirror(['USER', 'CHANNEL', 'GUILD_MEMBER', 'MESSAGE',
 * * STAGE_INSTANCE_DELETE
 * * GUILD_STICKERS_UPDATE
 * @typedef {string} WSEventType
+ * @see {@link https://discord.com/developers/docs/topics/gateway#commands-and-events-gateway-events}
 */
 exports.WSEvents = keyMirror([
  'READY',
@@ -332,6 +333,7 @@ exports.WSEvents = keyMirror([
 * * `gdm.join`: allows joining the user to a group dm
 * * `webhook.incoming`: generates a webhook to a channel
 * @typedef {string} InviteScope
+ * @see {@link https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes}
 */
 exports.InviteScopes = [
  'applications.builds.read',
@@ -356,7 +358,7 @@ exports.InviteScopes = [
 * * CALL
 * * CHANNEL_NAME_CHANGE
 * * CHANNEL_ICON_CHANGE
- * * PINS_ADD
+ * * CHANNEL_PINNED_MESSAGE
 * * GUILD_MEMBER_JOIN
 * * USER_PREMIUM_GUILD_SUBSCRIPTION
 * * USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_1
@@ -373,6 +375,7 @@ exports.InviteScopes = [
 * * THREAD_STARTER_MESSAGE
 * * GUILD_INVITE_REMINDER
 * @typedef {string} MessageType
+ * @see {@link https://discord.com/developers/docs/resources/channel#message-object-message-types}
 */
 exports.MessageTypes = [
  'DEFAULT',
@@ -381,7 +384,7 @@ exports.MessageTypes = [
  'CALL',
  'CHANNEL_NAME_CHANGE',
  'CHANNEL_ICON_CHANGE',
-  'PINS_ADD',
+  'CHANNEL_PINNED_MESSAGE',
  'GUILD_MEMBER_JOIN',
  'USER_PREMIUM_GUILD_SUBSCRIPTION',
  'USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_1',
@@ -413,7 +416,7 @@ exports.SystemMessageTypes = exports.MessageTypes.filter(

 /**
 * <info>Bots cannot set a `CUSTOM` activity type, it is only for custom statuses received from users</info>
- * The type of an activity of a users presence, e.g. `PLAYING`. Here are the available types:
+ * The type of an activity of a user's presence. Here are the available types:
 * * PLAYING
 * * STREAMING
 * * LISTENING
@@ -421,6 +424,7 @@ exports.SystemMessageTypes = exports.MessageTypes.filter(
 * * CUSTOM
 * * COMPETING
 * @typedef {string} ActivityType
+ * @see {@link https://discord.com/developers/docs/game-sdk/activities#data-models-activitytype-enum}
 */
 exports.ActivityTypes = createEnum(['PLAYING', 'STREAMING', 'LISTENING', 'WATCHING', 'CUSTOM', 'COMPETING']);

@@ -439,6 +443,7 @@ exports.ActivityTypes = createEnum(['PLAYING', 'STREAMING', 'LISTENING', 'WATCHI
 * * `GUILD_STAGE_VOICE` - a guild stage voice channel
 * * `UNKNOWN` - a generic channel of unknown type, could be Channel or GuildChannel
 * @typedef {string} ChannelType
+ * @see {@link https://discord.com/developers/docs/resources/channel#channel-object-channel-types}
 */
 exports.ChannelTypes = createEnum([
  'GUILD_TEXT',
@@ -545,6 +550,7 @@ exports.Colors = {
 * * MEMBERS_WITHOUT_ROLES
 * * ALL_MEMBERS
 * @typedef {string} ExplicitContentFilterLevel
+ * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-explicit-content-filter-level}
 */
 exports.ExplicitContentFilterLevels = createEnum(['DISABLED', 'MEMBERS_WITHOUT_ROLES', 'ALL_MEMBERS']);

@@ -556,6 +562,7 @@ exports.ExplicitContentFilterLevels = createEnum(['DISABLED', 'MEMBERS_WITHOUT_R
 * * HIGH
 * * VERY_HIGH
 * @typedef {string} VerificationLevel
+ * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-verification-level}
 */
 exports.VerificationLevels = createEnum(['NONE', 'LOW', 'MEDIUM', 'HIGH', 'VERY_HIGH']);

@@ -685,6 +692,7 @@ exports.VerificationLevels = createEnum(['NONE', 'LOW', 'MEDIUM', 'HIGH', 'VERY_
 * * MAXIMUM_ACTIVE_THREADS
 * * MAXIMUM_ACTIVE_ANNOUCEMENT_THREAD
 * @typedef {string} APIError
+ * @see {@link https://discord.com/developers/docs/topics/opcodes-and-status-codes#json-json-error-codes}
 */
 exports.APIErrors = {
  UNKNOWN_ACCOUNT: 10001,
@@ -827,6 +835,7 @@ exports.APIErrors = {
 * * ALL_MESSAGES
 * * ONLY_MENTIONS
 * @typedef {string} DefaultMessageNotificationLevel
+ * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-default-message-notification-level}
 */
 exports.DefaultMessageNotificationLevels = createEnum(['ALL_MESSAGES', 'ONLY_MENTIONS']);

@@ -835,6 +844,7 @@ exports.DefaultMessageNotificationLevels = createEnum(['ALL_MESSAGES', 'ONLY_MEN
 * * INVITED
 * * ACCEPTED
 * @typedef {string} MembershipState
+ * @see {@link https://discord.com/developers/docs/topics/teams#data-models-membership-state-enum}
 */
 exports.MembershipStates = createEnum([null, 'INVITED', 'ACCEPTED']);

@@ -842,15 +852,18 @@ exports.MembershipStates = createEnum([null, 'INVITED', 'ACCEPTED']);
 * The value set for a webhook's type:
 * * Incoming
 * * Channel Follower
+ * * Application
 * @typedef {string} WebhookType
+ * @see {@link https://discord.com/developers/docs/resources/webhook#webhook-object-webhook-types}
 */
-exports.WebhookTypes = createEnum([null, 'Incoming', 'Channel Follower']);
+exports.WebhookTypes = createEnum([null, 'Incoming', 'Channel Follower', 'Application']);

 /**
 * The value set for a sticker's type:
 * * STANDARD
 * * GUILD
 * @typedef {string} StickerType
+ * @see {@link https://discord.com/developers/docs/resources/sticker#sticker-object-sticker-types}
 */
 exports.StickerTypes = createEnum([null, 'STANDARD', 'GUILD']);

@@ -860,6 +873,7 @@ exports.StickerTypes = createEnum([null, 'STANDARD', 'GUILD']);
 * * APNG
 * * LOTTIE
 * @typedef {string} StickerFormatType
+ * @see {@link https://discord.com/developers/docs/resources/sticker#sticker-object-sticker-format-types}
 */
 exports.StickerFormatTypes = createEnum([null, 'PNG', 'APNG', 'LOTTIE']);

@@ -868,9 +882,11 @@ exports.StickerFormatTypes = createEnum([null, 'PNG', 'APNG', 'LOTTIE']);
 * * role
 * * member
 * @typedef {string} OverwriteType
+ * @see {@link https://discord.com/developers/docs/resources/channel#overwrite-object-overwrite-structure}
 */
 exports.OverwriteTypes = createEnum(['role', 'member']);

+/* eslint-disable max-len */
 /**
 * The type of an {@link ApplicationCommandOption} object:
 * * SUB_COMMAND
@@ -884,6 +900,7 @@ exports.OverwriteTypes = createEnum(['role', 'member']);
 * * MENTIONABLE
 * * NUMBER
 * @typedef {string} ApplicationCommandOptionType
+ * @see {@link https://discord.com/developers/docs/interactions/slash-commands#application-command-object-application-command-option-type}
 */
 exports.ApplicationCommandOptionTypes = createEnum([
  null,
@@ -904,6 +921,7 @@ exports.ApplicationCommandOptionTypes = createEnum([
 * * ROLE
 * * USER
 * @typedef {string} ApplicationCommandPermissionType
+ * @see {@link https://discord.com/developers/docs/interactions/slash-commands#application-command-permissions-object-application-command-permission-type}
 */
 exports.ApplicationCommandPermissionTypes = createEnum([null, 'ROLE', 'USER']);

@@ -913,6 +931,7 @@ exports.ApplicationCommandPermissionTypes = createEnum([null, 'ROLE', 'USER']);
 * * APPLICATION_COMMAND
 * * MESSAGE_COMPONENT
 * @typedef {string} InteractionType
+ * @see {@link https://discord.com/developers/docs/interactions/slash-commands#interaction-object-interaction-request-type}
 */
 exports.InteractionTypes = createEnum([null, 'PING', 'APPLICATION_COMMAND', 'MESSAGE_COMPONENT']);

@@ -924,6 +943,7 @@ exports.InteractionTypes = createEnum([null, 'PING', 'APPLICATION_COMMAND', 'MES
 * * DEFERRED_MESSAGE_UPDATE
 * * UPDATE_MESSAGE
 * @typedef {string} InteractionResponseType
+ * @see {@link https://discord.com/developers/docs/interactions/slash-commands#interaction-response-object-interaction-callback-type}
 */
 exports.InteractionResponseTypes = createEnum([
  null,
@@ -935,6 +955,7 @@ exports.InteractionResponseTypes = createEnum([
  'DEFERRED_MESSAGE_UPDATE',
  'UPDATE_MESSAGE',
 ]);
+/* eslint-enable max-len */

 /**
 * The type of a message component
@@ -942,6 +963,7 @@ exports.InteractionResponseTypes = createEnum([
 * * BUTTON
 * * SELECT_MENU
 * @typedef {string} MessageComponentType
+ * @see {@link https://discord.com/developers/docs/interactions/message-components#component-object-component-types}
 */
 exports.MessageComponentTypes = createEnum([null, 'ACTION_ROW', 'BUTTON', 'SELECT_MENU']);

@@ -953,6 +975,7 @@ exports.MessageComponentTypes = createEnum([null, 'ACTION_ROW', 'BUTTON', 'SELEC
 * * DANGER
 * * LINK
 * @typedef {string} MessageButtonStyle
+ * @see {@link https://discord.com/developers/docs/interactions/message-components#button-object-button-styles}
 */
 exports.MessageButtonStyles = createEnum([null, 'PRIMARY', 'SECONDARY', 'SUCCESS', 'DANGER', 'LINK']);

@@ -961,6 +984,7 @@ exports.MessageButtonStyles = createEnum([null, 'PRIMARY', 'SECONDARY', 'SUCCESS
 * * NONE
 * * ELEVATED
 * @typedef {string} MFALevel
+ * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-mfa-level}
 */
 exports.MFALevels = createEnum(['NONE', 'ELEVATED']);

@@ -971,6 +995,7 @@ exports.MFALevels = createEnum(['NONE', 'ELEVATED']);
 * * SAFE
 * * AGE_RESTRICTED
 * @typedef {string} NSFWLevel
+ * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-guild-nsfw-level}
 */
 exports.NSFWLevels = createEnum(['DEFAULT', 'EXPLICIT', 'SAFE', 'AGE_RESTRICTED']);

@@ -979,6 +1004,7 @@ exports.NSFWLevels = createEnum(['DEFAULT', 'EXPLICIT', 'SAFE', 'AGE_RESTRICTED'
 * * PUBLIC
 * * GUILD_ONLY
 * @typedef {string} PrivacyLevel
+ * @see {@link https://discord.com/developers/docs/resources/stage-instance#stage-instance-object-privacy-level}
 */
 exports.PrivacyLevels = createEnum([null, 'PUBLIC', 'GUILD_ONLY']);

@@ -989,6 +1015,7 @@ exports.PrivacyLevels = createEnum([null, 'PUBLIC', 'GUILD_ONLY']);
 * * TIER_2
 * * TIER_3
 * @typedef {string} PremiumTier
+ * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-premium-tier}
 */
 exports.PremiumTiers = createEnum(['NONE', 'TIER_1', 'TIER_2', 'TIER_3']);

--- a/src/util/LimitedCollection.js
+++ b/src/util/LimitedCollection.js
@@ -100,11 +100,11 @@ class LimitedCollection extends Collection {
  /**
   * Options for generating a filter function based on lifetime
   * @typedef {Object} LifetimeFilterOptions
-   * @property {number} [lifetime=14400] How long an entry should stay in the collection before it is considered
-   * sweepable.
-   * @property {Function} [getComparisonTimestamp=`e => e.createdTimestamp`] A function that takes an entry, key,
+   * @property {number} [lifetime=14400] How long, in seconds, an entry should stay in the collection
+   * before it is considered sweepable.
+   * @property {Function} [getComparisonTimestamp=e => e?.createdTimestamp] A function that takes an entry, key,
   * and the collection and returns a timestamp to compare against in order to determine the lifetime of the entry.
-   * @property {Function} [excludeFromSweep=`() => false`] A function that takes an entry, key, and the collection
+   * @property {Function} [excludeFromSweep=() => false] A function that takes an entry, key, and the collection
   * and returns a boolean, `true` when the entry should not be checked for sweepability.
   */

--- a/src/util/Permissions.js
+++ b/src/util/Permissions.js
@@ -57,10 +57,10 @@ class Permissions extends BitField {

 /**
 * Numeric permission flags. All available properties:
- * * `ADMINISTRATOR` (implicitly has *all* permissions, and bypasses all channel overwrites)
 * * `CREATE_INSTANT_INVITE` (create invitations to the guild)
 * * `KICK_MEMBERS`
 * * `BAN_MEMBERS`
+ * * `ADMINISTRATOR` (implicitly has *all* permissions, and bypasses all channel overwrites)
 * * `MANAGE_CHANNELS` (edit and reorder channels)
 * * `MANAGE_GUILD` (edit the guild information, region, etc.)
 * * `ADD_REACTIONS` (add new reactions to messages)
@@ -95,7 +95,7 @@ class Permissions extends BitField {
 * * `USE_PRIVATE_THREADS`
 * * `USE_EXTERNAL_STICKERS` (use stickers from different guilds)
 * @type {Object<string, bigint>}
- * @see {@link https://discord.com/developers/docs/topics/permissions}
+ * @see {@link https://discord.com/developers/docs/topics/permissions#permissions-bitwise-permission-flags}
 */
 Permissions.FLAGS = {
  CREATE_INSTANT_INVITE: 1n << 0n,
--- a/src/util/SnowflakeUtil.js
+++ b/src/util/SnowflakeUtil.js
@@ -11,10 +11,11 @@ let INCREMENT = 0;
 */
 class SnowflakeUtil extends null {
  /**
-   * A Twitter snowflake, except the epoch is 2015-01-01T00:00:00.000Z
-   * ```
-   * If we have a snowflake '266241948824764416' we can represent it as binary:
+   * A {@link https://developer.twitter.com/en/docs/twitter-ids Twitter snowflake},
+   * except the epoch is 2015-01-01T00:00:00.000Z.
   *
+   * If we have a snowflake '266241948824764416' we can represent it as binary:
+   * ```
   * 64                                          22     17     12          0
   *  000000111011000111100001101001000101000000  00001  00000  000000000000
   *       number of ms since Discord epoch       worker  pid    increment
@@ -56,7 +57,7 @@ class SnowflakeUtil extends null {
  /**
   * Deconstructs a Discord snowflake.
   * @param {Snowflake} snowflake Snowflake to deconstruct
-   * @returns {DeconstructedSnowflake} Deconstructed snowflake
+   * @returns {DeconstructedSnowflake}
   */
  static deconstruct(snowflake) {
    const BINARY = Util.idToBinary(snowflake).toString(2).padStart(64, '0');
--- a/src/util/SystemChannelFlags.js
+++ b/src/util/SystemChannelFlags.js
@@ -38,6 +38,7 @@ class SystemChannelFlags extends BitField {}
 * * `SUPPRESS_PREMIUM_SUBSCRIPTIONS` (Suppress server boost notifications)
 * * `SUPPRESS_GUILD_REMINDER_NOTIFICATIONS` (Suppress server setup tips)
 * @type {Object}
+ * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-system-channel-flags}
 */
 SystemChannelFlags.FLAGS = {
  SUPPRESS_JOIN_NOTIFICATIONS: 1 << 0,