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>

src/client/Client.js

@@ -610,3 +610,8 @@ module.exports = Client;
  * @event Client#debug
  * @param {string} info The debug information
  */
+
+/**
+ * @external Collection
+ * @see {@link https://discord.js.org/#/docs/collection/master/class/Collection}
+ */

src/client/websocket/WebSocketManager.js

@@ -175,7 +175,7 @@ class WebSocketManager extends EventEmitter {
          * Emitted when a shard turns ready.
          * @event Client#shardReady
          * @param {number} id The shard id that turned ready
-         * @param {?Set<string>} unavailableGuilds Set of unavailable guild ids, if any
+         * @param {?Set<Snowflake>} unavailableGuilds Set of unavailable guild ids, if any
          */
         this.client.emit(Events.SHARD_READY, shard.id, unavailableGuilds);
 

src/client/websocket/handlers/GUILD_MEMBERS_CHUNK.js

@@ -12,15 +12,21 @@ module.exports = (client, { d: data }) => {
   if (data.presences) {
     for (const presence of data.presences) guild.presences._add(Object.assign(presence, { guild }));
   }
+
+  /**
+   * Represents the properties of a guild members chunk
+   * @typedef {Object} GuildMembersChunk
+   * @property {number} index Index of the received chunk
+   * @property {number} count Number of chunks the client should receive
+   * @property {?string} nonce Nonce for this chunk
+   */
+
   /**
    * Emitted whenever a chunk of guild members is received (all members come from the same guild).
    * @event Client#guildMembersChunk
    * @param {Collection<Snowflake, GuildMember>} members The members in the chunk
    * @param {Guild} guild The guild related to the member chunk
-   * @param {Object} chunk Properties of the received chunk
-   * @param {number} chunk.index Index of the received chunk
-   * @param {number} chunk.count Number of chunks the client should receive
-   * @param {?string} chunk.nonce Nonce for this chunk
+   * @param {GuildMembersChunk} chunk Properties of the received chunk
    */
   client.emit(Events.GUILD_MEMBERS_CHUNK, members, guild, {
     count: data.chunk_count,

src/managers/ApplicationCommandPermissionsManager.js

@@ -124,7 +124,7 @@ class ApplicationCommandPermissionsManager extends BaseManager {
    * @typedef {BaseApplicationCommandPermissionsOptions} SetApplicationCommandPermissionsOptions
    * @param {ApplicationCommandPermissionData[]} [permissions] The new permissions for the command
    * @param {GuildApplicationCommandPermissionData[]} [fullPermissions] The new permissions for all commands
-   * in a guild <warn>When this parameter is set, permissions and command are ignored</warn>
+   * in a guild <warn>When this parameter is set, `permissions` and `command` are ignored</warn>
    */
 
   /**

src/managers/GuildBanManager.js

@@ -62,7 +62,7 @@ class GuildBanManager extends CachedManager {
   /**
    * Fetches ban(s) from Discord.
    * @param {UserResolvable|FetchBanOptions|FetchBansOptions} [options] Options for fetching guild ban(s)
-   * @returns {Promise<GuildBan>|Promise<Collection<Snowflake, GuildBan>>}
+   * @returns {Promise<GuildBan|Collection<Snowflake, GuildBan>>}
    * @example
    * // Fetch all bans from a guild
    * guild.bans.fetch()
@@ -135,7 +135,7 @@ class GuildBanManager extends CachedManager {
    * @example
    * // Ban a user by id (or with a user/guild member object)
    * guild.bans.create('84484653687267328')
-   *   .then(user => console.log(`Banned ${user.username ?? user.id ?? user} from ${guild.name}`))
+   *   .then(banInfo => console.log(`Banned ${banInfo.user?.tag ?? banInfo.tag ?? banInfo}`))
    *   .catch(console.error);
    */
   async create(user, options = { days: 0 }) {

src/managers/GuildManager.js

@@ -72,7 +72,7 @@ class GuildManager extends CachedManager {
   /**
    * Partial overwrite data.
    * @typedef {Object} PartialOverwriteData
-   * @property {Snowflake|number} id The {@link Role} or {@link User} id for this overwrite
+   * @property {Snowflake|number} id The id of the {@link Role} or {@link User} this overwrite belongs to
    * @property {string} [type] The type of this overwrite
    * @property {PermissionResolvable} [allow] The permissions to allow
    * @property {PermissionResolvable} [deny] The permissions to deny

src/managers/GuildMemberManager.js

@@ -139,7 +139,7 @@ class GuildMemberManager extends CachedManager {
    * @param {UserResolvable|FetchMemberOptions|FetchMembersOptions} [options] If a UserResolvable, the user to fetch.
    * If undefined, fetches all members.
    * If a query, it limits the results to users with similar usernames.
-   * @returns {Promise<GuildMember>|Promise<Collection<Snowflake, GuildMember>>}
+   * @returns {Promise<GuildMember|Collection<Snowflake, GuildMember>>}
    * @example
    * // Fetch all members from a guild
    * guild.members.fetch()
@@ -248,6 +248,8 @@ class GuildMemberManager extends CachedManager {
 
   /**
    * Options used for pruning guild members.
+   * <info>It's recommended to set {@link GuildPruneMembersOptions#count options.count}
+   * to `false` for large guilds.</info>
    * @typedef {Object} GuildPruneMembersOptions
    * @property {number} [days=7] Number of days of inactivity required to kick
    * @property {boolean} [dry=false] Get the number of users that will be kicked, without actually kicking them
@@ -258,7 +260,6 @@ class GuildMemberManager extends CachedManager {
 
   /**
    * Prunes members from the guild based on how long they have been inactive.
-   * <info>It's recommended to set `options.count` to `false` for large guilds.</info>
    * @param {GuildPruneMembersOptions} [options] Options for pruning
    * @returns {Promise<number|null>} The number of members that were/will be kicked
    * @example
@@ -315,7 +316,7 @@ class GuildMemberManager extends CachedManager {
    * @example
    * // Kick a user by id (or with a user/guild member object)
    * guild.members.kick('84484653687267328')
-   *   .then(user => console.log(`Kicked ${user.username ?? user.id ?? user} from ${guild.name}`))
+   *   .then(banInfo => console.log(`Kicked ${banInfo.user?.tag ?? banInfo.tag ?? banInfo}`))
    *   .catch(console.error);
    */
   async kick(user, reason) {
@@ -338,19 +339,18 @@ class GuildMemberManager extends CachedManager {
    * @example
    * // Ban a user by id (or with a user/guild member object)
    * guild.members.ban('84484653687267328')
-   *   .then(user => console.log(`Banned ${user.username ?? user.id ?? user} from ${guild.name}`))
+   *   .then(kickInfo => console.log(`Banned ${kickInfo.user?.tag ?? kickInfo.tag ?? kickInfo}`))
    *   .catch(console.error);
    */
   ban(user, options = { days: 0 }) {
     return this.guild.bans.create(user, options);
   }
 
   /**
-   * Unbans a user from the guild.
+   * Unbans a user from the guild. Internally calls the {@link GuildBanManager#remove} method.
    * @param {UserResolvable} user The user to unban
    * @param {string} [reason] Reason for unbanning user
-   * @returns {Promise<User>}
-   * Internally calls the GuildBanManager#remove method.
+   * @returns {Promise<User>} The user that was unbanned
    * @example
    * // Unban a user by id (or with a user/guild member object)
    * guild.members.unban('84484653687267328')

src/managers/GuildStickerManager.js

@@ -31,14 +31,19 @@ class GuildStickerManager extends CachedManager {
     return super._add(data, cache, { extras: [this.guild] });
   }
 
+  /**
+   * Options for creating a guild sticker.
+   * @typedef {Object} GuildStickerCreateOptions
+   * @param {?string} [description] The description for the sticker
+   * @param {string} [reason] Reason for creating the sticker
+   */
+
   /**
    * Creates a new custom sticker in the guild.
    * @param {BufferResolvable|Stream|FileOptions|MessageAttachment} file The file for the sticker
    * @param {string} name The name for the sticker
    * @param {string} tags The Discord name of a unicode emoji representing the sticker's expression
-   * @param {Object} [options] Options
-   * @param {?string} [options.description] The description for the sticker
-   * @param {string} [options.reason] Reason for creating the sticker
+   * @param {GuildStickerCreateOptions} [options] Options
    * @returns {Promise<Sticker>} The created sticker
    * @example
    * // Create a new sticker from a url

src/managers/MessageManager.js

@@ -47,7 +47,7 @@ class MessageManager extends CachedManager {
    * Those need to be fetched separately in such a case.</info>
    * @param {Snowflake|ChannelLogsQueryOptions} [message] The id of the message to fetch, or query parameters.
    * @param {BaseFetchOptions} [options] Additional options for this fetch
-   * @returns {Promise<Message>|Promise<Collection<Snowflake, Message>>}
+   * @returns {Promise<Message|Collection<Snowflake, Message>>}
    * @example
    * // Get message
    * channel.messages.fetch('99539446449315840')
@@ -165,7 +165,7 @@ class MessageManager extends CachedManager {
   }
 
   /**
-   * Unins a message from the channel's pinned messages, even if it's not cached.
+   * Unpins a message from the channel's pinned messages, even if it's not cached.
    * @param {MessageResolvable} message The message to unpin
    * @returns {Promise<void>}
    */

src/managers/ThreadManager.js

@@ -144,7 +144,7 @@ class ThreadManager extends CachedManager {
    * @param {ThreadChannelResolvable|FetchThreadsOptions} [options] The options to fetch threads. If it is a
    * ThreadChannelResolvable then the specified thread will be fetched. Fetches all active threads if `undefined`
    * @param {BaseFetchOptions} [cacheOptions] Additional options for this fetch. <warn>The `force` field gets ignored
-   * if `options` is not a ThreadChannelResolvable</warn>
+   * if `options` is not a {@link ThreadChannelResolvable}</warn>
    * @returns {Promise<?(ThreadChannel|FetchedThreads)>}
    * @example
    * // Fetch a thread by its id

src/sharding/ShardClientUtil.js

@@ -100,7 +100,7 @@ class ShardClientUtil {
    * Fetches a client property value of each shard, or a given shard.
    * @param {string} prop Name of the client property to get, using periods for nesting
    * @param {number} [shard] Shard to fetch property from, all if undefined
-   * @returns {Promise<*>|Promise<Array<*>>}
+   * @returns {Promise<*|Array<*>>}
    * @example
    * client.shard.fetchClientValues('guilds.cache.size')
    *   .then(results => console.log(`${results.reduce((prev, val) => prev + val, 0)} total guilds`))
@@ -130,7 +130,7 @@ class ShardClientUtil {
    * Evaluates a script or function on all shards, or a given shard, in the context of the {@link Client}s.
    * @param {Function} script JavaScript to run on each shard
    * @param {BroadcastEvalOptions} [options={}] The options for the broadcast
-   * @returns {Promise<*>|Promise<Array<*>>} Results of the script execution
+   * @returns {Promise<*|Array<*>>} Results of the script execution
    * @example
    * client.shard.broadcastEval(client => client.guilds.cache.size)
    *   .then(results => console.log(`${results.reduce((prev, val) => prev + val, 0)} total guilds`))

src/sharding/ShardingManager.js

@@ -19,8 +19,9 @@ const Util = require('../util/Util');
  */
 class ShardingManager extends EventEmitter {
   /**
-   * The mode to spawn shards with for a {@link ShardingManager}. Either "process" to use child processes, or
-   * "worker" to use [Worker threads](https://nodejs.org/api/worker_threads.html).
+   * The mode to spawn shards with for a {@link ShardingManager}. Can be either one of:
+   * * 'process' to use child processes
+   * * 'worker' to use [Worker threads](https://nodejs.org/api/worker_threads.html)
    * @typedef {string} ShardingManagerMode
    */
 
@@ -242,7 +243,7 @@ class ShardingManager extends EventEmitter {
    * Evaluates a script on all shards, or a given shard, in the context of the {@link Client}s.
    * @param {Function} script JavaScript to run on each shard
    * @param {BroadcastEvalOptions} [options={}] The options for the broadcast
-   * @returns {Promise<*>|Promise<Array<*>>} Results of the script execution
+   * @returns {Promise<*|Array<*>>} Results of the script execution
    */
   broadcastEval(script, options = {}) {
     if (typeof script !== 'function') return Promise.reject(new TypeError('SHARDING_INVALID_EVAL_BROADCAST'));
@@ -253,7 +254,7 @@ class ShardingManager extends EventEmitter {
    * Fetches a client property value of each shard, or a given shard.
    * @param {string} prop Name of the client property to get, using periods for nesting
    * @param {number} [shard] Shard to fetch property from, all if undefined
-   * @returns {Promise<*>|Promise<Array<*>>}
+   * @returns {Promise<*|Array<*>>}
    * @example
    * manager.fetchClientValues('guilds.cache.size')
    *   .then(results => console.log(`${results.reduce((prev, val) => prev + val, 0)} total guilds`))
@@ -268,7 +269,7 @@ class ShardingManager extends EventEmitter {
    * @param {string} method Method name to run on each shard
    * @param {Array<*>} args Arguments to pass through to the method call
    * @param {number} [shard] Shard to run on, all if undefined
-   * @returns {Promise<*>|Promise<Array<*>>} Results of the method execution
+   * @returns {Promise<*|Array<*>>} Results of the method execution
    * @private
    */
   _performOnShards(method, args, shard) {

src/structures/BaseMessageComponent.js

@@ -23,11 +23,12 @@ class BaseMessageComponent {
    */
 
   /**
-   * Components that can be sent in a message. This can be:
+   * Components that can be sent in a message. These can be:
    * * MessageActionRow
    * * MessageButton
    * * MessageSelectMenu
    * @typedef {MessageActionRow|MessageButton|MessageSelectMenu} MessageComponent
+   * @see {@link https://discord.com/developers/docs/interactions/message-components#component-object-component-types}
    */
 
   /**

src/structures/ClientUser.js

@@ -41,11 +41,16 @@ class ClientUser extends User {
     return this.client.presence;
   }
 
+  /**
+   * Data used to edit the logged in client
+   * @typdef {Object} ClientUserEditData
+   * @property {string} [username] The new username
+   * @property {BufferResolvable|Base64Resolvable} [avatar] The new avatar
+   */
+
   /**
    * Edits the logged in client.
-   * @param {APIModifyClientData} data The new data
-   * @param {string} [data.username] The new username
-   * @param {BufferResolvable|Base64Resolvable} [data.avatar] The new avatar
+   * @param {ClientUserEditData} data The new data
    */
   async edit(data) {
     const newData = await this.client.api.users('@me').patch({ data });
@@ -172,8 +177,3 @@ class ClientUser extends User {
 }
 
 module.exports = ClientUser;
-
-/**
- * @external APIModifyClientData
- * @see {@link https://discord.com/developers/docs/resources/user#modify-current-user-json-params}
- */

src/structures/Guild.js

@@ -37,7 +37,7 @@ const Util = require('../util/Util');
 /**
  * Represents a guild (or a server) on Discord.
  * <info>It's recommended to see if a guild is available before performing operations or reading data from it. You can
- * check this with `guild.available`.</info>
+ * check this with {@link Guild#available}.</info>
  * @extends {AnonymousGuild}
  */
 class Guild extends AnonymousGuild {
@@ -172,21 +172,21 @@ class Guild extends AnonymousGuild {
      * * FEATURABLE
      * * INVITE_SPLASH
      * * MEMBER_VERIFICATION_GATE_ENABLED
-     * * MONETIZATION_ENABLED
-     * * MORE_STICKERS
      * * NEWS
      * * PARTNERED
      * * PREVIEW_ENABLED
-     * * PRIVATE_THREADS
-     * * RELAY_ENABLED
-     * * SEVEN_DAY_THREAD_ARCHIVE
-     * * THREE_DAY_THREAD_ARCHIVE
-     * * TICKETED_EVENTS_ENABLED
      * * VANITY_URL
      * * VERIFIED
      * * VIP_REGIONS
      * * WELCOME_SCREEN_ENABLED
+     * * TICKETED_EVENTS_ENABLED
+     * * MONETIZATION_ENABLED
+     * * MORE_STICKERS
+     * * THREE_DAY_THREAD_ARCHIVE
+     * * SEVEN_DAY_THREAD_ARCHIVE
+     * * PRIVATE_THREADS
      * @typedef {string} Features
+     * @see {@link https://discord.com/developers/docs/resources/guild#guild-object-guild-features}
      */
 
     /**
@@ -337,7 +337,8 @@ class Guild extends AnonymousGuild {
 
     /**
      * The preferred locale of the guild, defaults to `en-US`
-     * @type {string}
+     * @type {?string}
+     * @see {@link https://discord.com/developers/docs/dispatch/field-values#predefined-field-values-accepted-locales}
      */
     this.preferredLocale = data.preferred_locale;
 

src/structures/GuildAuditLogs.js

@@ -11,7 +11,7 @@ const SnowflakeUtil = require('../util/SnowflakeUtil');
 const Util = require('../util/Util');
 
 /**
- * The target type of an entry, e.g. `GUILD`. Here are the available types:
+ * The target type of an entry. Here are the available types:
  * * GUILD
  * * CHANNEL
  * * USER
@@ -97,6 +97,7 @@ const Targets = {
  * * THREAD_UPDATE: 111
  * * THREAD_DELETE: 112
  * @typedef {?(number|string)} AuditLogAction
+ * @see {@link https://discord.com/developers/docs/resources/audit-log#audit-log-entry-object-audit-log-events}
  */
 
 /**

src/structures/GuildBan.js

@@ -41,8 +41,7 @@ class GuildBan extends Base {
   }
 
   /**
-   * Whether this GuildBan is a partial
-   * If the reason is not provided the value is null
+   * Whether this GuildBan is partial. If the reason is not provided the value is null
    * @type {boolean}
    * @readonly
    */

src/structures/InteractionCollector.js

@@ -19,8 +19,8 @@ const { InteractionTypes, MessageComponentTypes } = require('../util/Constants')
 
 /**
  * Collects interactions.
- * Will automatically stop if the message (`'messageDelete'`),
- * channel (`'channelDelete'`), or guild (`'guildDelete'`) are deleted.
+ * Will automatically stop if the message ({@link Client#messageDelete messageDelete}),
+ * channel ({@link Client#channelDelete channelDelete}), or guild ({@link Client#guildDelete guildDelete}) is deleted.
  * @extends {Collector}
  */
 class InteractionCollector extends Collector {
@@ -76,7 +76,7 @@ class InteractionCollector extends Collector {
 
     /**
      * The users which have interacted to this collector
-     * @type {Collection}
+     * @type {Collection<Snowflake, User>}
      */
     this.users = new Collection();
 

src/structures/Invite.js

@@ -97,6 +97,7 @@ class Invite extends Base {
      * * 1: STREAM
      * * 2: EMBEDDED_APPLICATION
      * @typedef {number} TargetType
+     * @see {@link https://discord.com/developers/docs/resources/invite#invite-object-invite-target-types}
      */
 
     /**