refactor(*): make typedefs for all options params (#5785)

Co-authored-by: Rodry <38259440+ImRodry@users.noreply.github.com>
Co-authored-by: Antonio Román <kyradiscord@gmail.com>
Co-authored-by: Vlad Frangu <kingdgrizzle@gmail.com>

src/structures/CategoryChannel.js

@@ -22,10 +22,8 @@ class CategoryChannel extends GuildChannel {
    * @method setParent
    * @memberof CategoryChannel
    * @instance
-   * @param {?GuildChannel|Snowflake} channel Parent channel
-   * @param {Object} [options={}] Options to pass
-   * @param {boolean} [options.lockPermissions=true] Lock the permissions to what the parent's permissions are
-   * @param {string} [options.reason] Reason for modifying the parent of this channel
+   * @param {?(GuildChannel|Snowflake)} channel The channel to set as parent
+   * @param {SetParentOptions} [options={}] The options for setting the parent
    * @returns {Promise<GuildChannel>}
    */
 }

src/structures/Guild.js

@@ -727,13 +727,18 @@ class Guild extends BaseGuild {
     };
   }
 
+  /**
+   * Options used to fetch audit logs.
+   * @typedef {Object} GuildAuditLogsFetchOptions
+   * @property {Snowflake|GuildAuditLogsEntry} [before] Only return entries before this entry
+   * @property {number} [limit] The number of entries to return
+   * @property {UserResolvable} [user] Only return entries for actions made by this user
+   * @property {AuditLogAction|number} [type] Only return entries for this action type
+   */
+
   /**
    * Fetches audit logs for this guild.
-   * @param {Object} [options={}] Options for fetching audit logs
-   * @param {Snowflake|GuildAuditLogsEntry} [options.before] Limit to entries from before specified entry
-   * @param {number} [options.limit] Limit number of entries
-   * @param {UserResolvable} [options.user] Only show entries involving this user
-   * @param {AuditLogAction|number} [options.type] Only show entries involving this action type
+   * @param {GuildAuditLogsFetchOptions} [options={}] Options for fetching audit logs
    * @returns {Promise<GuildAuditLogs>}
    * @example
    * // Output audit log entries
@@ -759,16 +764,21 @@ class Guild extends BaseGuild {
   }
 
   /**
-   * Adds a user to the guild using OAuth2. Requires the `CREATE_INSTANT_INVITE` permission.
-   * @param {UserResolvable} user User to add to the guild
-   * @param {Object} options Options for the addition
-   * @param {string} options.accessToken An OAuth2 access token for the user with the `guilds.join` scope granted to the
+   * Options used to add a user to a guild using OAuth2.
+   * @typedef {Object} AddGuildMemberOptions
+   * @property {string} accessToken An OAuth2 access token for the user with the `guilds.join` scope granted to the
    * bot's application
-   * @param {string} [options.nick] Nickname to give the member (requires `MANAGE_NICKNAMES`)
-   * @param {Collection<Snowflake, Role>|RoleResolvable[]} [options.roles] Roles to add to the member
+   * @property {string} [nick] The nickname to give to the member (requires `MANAGE_NICKNAMES`)
+   * @property {Collection<Snowflake, Role>|RoleResolvable[]} [roles] The roles to add to the member
    * (requires `MANAGE_ROLES`)
-   * @param {boolean} [options.mute] Whether the member should be muted (requires `MUTE_MEMBERS`)
-   * @param {boolean} [options.deaf] Whether the member should be deafened (requires `DEAFEN_MEMBERS`)
+   * @property {boolean} [mute] Whether the member should be muted (requires `MUTE_MEMBERS`)
+   * @property {boolean} [deaf] Whether the member should be deafened (requires `DEAFEN_MEMBERS`)
+   */
+
+  /**
+   * Adds a user to the guild using OAuth2. Requires the `CREATE_INSTANT_INVITE` permission.
+   * @param {UserResolvable} user The user to add to the guild
+   * @param {AddGuildMemberOptions} options Options for adding the user to the guild
    * @returns {Promise<GuildMember>}
    */
   async addMember(user, options) {

src/structures/GuildChannel.js

@@ -452,11 +452,16 @@ class GuildChannel extends Channel {
   }
 
   /**
-   * Sets the category parent of this channel.
-   * @param {?CategoryChannel|Snowflake} channel Parent channel
-   * @param {Object} [options={}] Options to pass
-   * @param {boolean} [options.lockPermissions=true] Lock the permissions to what the parent's permissions are
-   * @param {string} [options.reason] Reason for modifying the parent of this channel
+   * Options used to set parent of a channel.
+   * @typedef {Object} SetParentOptions
+   * @property {boolean} [lockPermissions=true] Whether to lock the permissions to what the parent's permissions are
+   * @property {string} [reason] The reason for modifying the parent of the channel
+   */
+
+  /**
+   * Sets the parent of this channel.
+   * @param {?(CategoryChannel|Snowflake)} channel The category channel to set as parent
+   * @param {SetParentOptions} [options={}] The options for setting the parent
    * @returns {Promise<GuildChannel>}
    * @example
    * // Add a parent to a channel
@@ -490,12 +495,17 @@ class GuildChannel extends Channel {
     return this.edit({ topic }, reason);
   }
 
+  /**
+   * Options used to set position of a channel.
+   * @typedef {Object} SetChannelPositionOptions
+   * @param {boolean} [relative=false] Whether or not to change the position relative to its current value
+   * @param {string} [reason] The reason for changing the position
+   */
+
   /**
    * Sets a new position for the guild channel.
    * @param {number} position The new position for the guild channel
-   * @param {Object} [options] Options for setting position
-   * @param {boolean} [options.relative=false] Change the position relative to its current value
-   * @param {string} [options.reason] Reason for changing the position
+   * @param {SetChannelPositionOptions} [options] Options for setting position
    * @returns {Promise<GuildChannel>}
    * @example
    * // Set a new channel position
@@ -529,19 +539,24 @@ class GuildChannel extends Channel {
    */
 
   /**
-   * Creates an invite to this guild channel.
-   * @param {Object} [options={}] Options for the invite
-   * @param {boolean} [options.temporary=false] Whether members that joined via the invite should be automatically
+   * Options used to create an invite to a guild channel.
+   * @typedef {Object} CreateInviteOptions
+   * @property {boolean} [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)
-   * @param {number} [options.maxUses=0] Maximum number of uses
-   * @param {boolean} [options.unique=false] Create a unique invite, or use an existing one with similar settings
-   * @param {UserResolvable} [options.targetUser] The user whose stream to display for this invite,
+   * @property {number} [maxAge=86400] How long the invite should last (in seconds, 0 for forever)
+   * @property {number} [maxUses=0] Maximum number of uses
+   * @property {boolean} [unique=false] Create a unique invite, or use an existing one with similar settings
+   * @property {UserResolvable} [targetUser] The user whose stream to display for this invite,
    * required if `targetType` is 1, the user must be streaming in the channel
-   * @param {ApplicationResolvable} [options.targetApplication] The embedded application to open for this invite,
+   * @property {ApplicationResolvable} [targetApplication] The embedded application to open for this invite,
    * required if `targetType` is 2, the application must have the `EMBEDDED` flag
-   * @param {InviteTargetType} [options.targetType] The type of the target for this voice channel invite
-   * @param {string} [options.reason] Reason for creating this
+   * @property {InviteTargetType} [targetType] The type of the target for this voice channel invite
+   * @property {string} [reason] The reason for creating the invite
+   */
+
+  /**
+   * Creates an invite to this guild channel.
+   * @param {CreateInviteOptions} [options={}] The options for creating the invite
    * @returns {Promise<Invite>}
    * @example
    * // Create an invite to a channel
@@ -591,22 +606,15 @@ class GuildChannel extends Channel {
     return invites;
   }
 
-  /* eslint-disable max-len */
+  /**
+   * Options used to clone a guild channel.
+   * @typedef {GuildChannelCreateOptions} GuildChannelCloneOptions
+   * @property {string} [name=this.name] Name of the new channel
+   */
+
   /**
    * Clones this channel.
-   * @param {Object} [options] The options
-   * @param {string} [options.name=this.name] Name of the new channel
-   * @param {OverwriteResolvable[]|Collection<Snowflake, OverwriteResolvable>} [options.permissionOverwrites=this.permissionOverwrites]
-   * Permission overwrites of the new channel
-   * @param {string} [options.type=this.type] Type of the new channel
-   * @param {string} [options.topic=this.topic] Topic of the new channel (only text)
-   * @param {boolean} [options.nsfw=this.nsfw] Whether the new channel is nsfw (only text)
-   * @param {number} [options.bitrate=this.bitrate] Bitrate of the new channel in bits (only voice)
-   * @param {number} [options.userLimit=this.userLimit] Maximum amount of users allowed in the new channel (only voice)
-   * @param {number} [options.rateLimitPerUser=this.rateLimitPerUser] Ratelimit per user for the new channel (only text)
-   * @param {number} [options.position=this.position] Position of the new channel
-   * @param {ChannelResolvable} [options.parent=this.parent] Parent of the new channel
-   * @param {string} [options.reason] Reason for cloning this channel
+   * @param {GuildChannelCloneOptions} [options] The options for cloning this channel
    * @returns {Promise<GuildChannel>}
    */
   clone(options = {}) {
@@ -624,7 +632,6 @@ class GuildChannel extends Channel {
       ...options,
     });
   }
-  /* eslint-enable max-len */
 
   /**
    * Checks if this channel has the same type, topic, position, name, overwrites and ID as another channel.

src/structures/GuildMember.js

@@ -323,9 +323,7 @@ class GuildMember extends Base {
 
   /**
    * Bans this guild member.
-   * @param {Object} [options] Options for the ban
-   * @param {number} [options.days=0] Number of days of messages to delete, must be between 0 and 7, inclusive
-   * @param {string} [options.reason] Reason for banning
+   * @param {BanOptions} [options] Options for the ban
    * @returns {Promise<GuildMember>}
    * @example
    * // ban a guild member

src/structures/GuildTemplate.js

@@ -136,10 +136,15 @@ class GuildTemplate extends Base {
   }
 
   /**
-   * Updates the metadata on this template.
-   * @param {Object} options Options for the template
-   * @param {string} [options.name] The name of this template
-   * @param {string} [options.description] The description of this template
+   * Options used to edit a guild template.
+   * @typedef {Object} EditGuildTemplateOptions
+   * @property {string} [name] The name of this template
+   * @property {string} [description] The description of this template
+   */
+
+  /**
+   * Updates the metadata of this template.
+   * @param {EditGuildTemplateOptions} [options] Options for editing the template
    * @returns {Promise<GuildTemplate>}
    */
   edit({ name, description } = {}) {

src/structures/MessageComponentInteractionCollector.js

@@ -83,7 +83,7 @@ class MessageComponentInteractionCollector extends Collector {
   /**
    * Handles an incoming interaction for possible collection.
    * @param {Interaction} interaction The interaction to possibly collect
-   * @returns {?Snowflake|string}
+   * @returns {?(Snowflake|string)}
    * @private
    */
   collect(interaction) {

src/structures/MessageMentions.js

@@ -161,14 +161,19 @@ class MessageMentions {
     return this._channels;
   }
 
+  /**
+   * Options used to check for a mention.
+   * @typedef {Object} MessageMentionsHasOptions
+   * @property {boolean} [ignoreDirect=false] Whether to ignore direct mentions to the item
+   * @property {boolean} [ignoreRoles=false] Whether to ignore role mentions to a guild member
+   * @property {boolean} [ignoreEveryone=false] Whether to ignore everyone/here mentions
+   */
+
   /**
    * Checks if a user, guild member, role, or channel is mentioned.
-   * Takes into account user mentions, role mentions, and @everyone/@here mentions.
-   * @param {UserResolvable|RoleResolvable|ChannelResolvable} data User/Role/Channel to check
-   * @param {Object} [options] Options
-   * @param {boolean} [options.ignoreDirect=false] - Whether to ignore direct mentions to the item
-   * @param {boolean} [options.ignoreRoles=false] - Whether to ignore role mentions to a guild member
-   * @param {boolean} [options.ignoreEveryone=false] - Whether to ignore everyone/here mentions
+   * Takes into account user mentions, role mentions, and `@everyone`/`@here` mentions.
+   * @param {UserResolvable|RoleResolvable|ChannelResolvable} data The User/Role/Channel to check for
+   * @param {MessageMentionsHasOptions} [options] The options for the check
    * @returns {boolean}
    */
   has(data, { ignoreDirect = false, ignoreRoles = false, ignoreEveryone = false } = {}) {

src/structures/ReactionCollector.js

@@ -82,7 +82,7 @@ class ReactionCollector extends Collector {
    * Handles an incoming reaction for possible collection.
    * @param {MessageReaction} reaction The reaction to possibly collect
    * @param {User} user The user that added the reaction
-   * @returns {?Snowflake|string}
+   * @returns {?(Snowflake|string)}
    * @private
    */
   collect(reaction, user) {
@@ -113,7 +113,7 @@ class ReactionCollector extends Collector {
    * Handles a reaction deletion for possible disposal.
    * @param {MessageReaction} reaction The reaction to possibly dispose of
    * @param {User} user The user that removed the reaction
-   * @returns {?Snowflake|string}
+   * @returns {?(Snowflake|string)}
    */
   dispose(reaction, user) {
     /**

src/structures/Role.js

@@ -323,11 +323,16 @@ class Role extends Base {
   }
 
   /**
-   * Sets the position of the role.
-   * @param {number} position The position of the role
-   * @param {Object} [options] Options for setting position
-   * @param {boolean} [options.relative=false] Change the position relative to its current value
-   * @param {string} [options.reason] Reason for changing the position
+   * Options used to set position of a role.
+   * @typedef {Object} SetRolePositionOptions
+   * @property {boolean} [relative=false] Whether to change the position relative to its current value or not
+   * @property {string} [reason] The reason for changing the position
+   */
+
+  /**
+   * Sets the new position of the role.
+   * @param {number} position The new position for the role
+   * @param {SetRolePositionOptions} [options] Options for setting the position
    * @returns {Promise<Role>}
    * @example
    * // Set the position of the role

src/structures/interfaces/Collector.js

@@ -194,10 +194,16 @@ class Collector extends EventEmitter {
   }
 
   /**
-   * Resets the collectors timeout and idle timer.
-   * @param {Object} [options] Options
-   * @param {number} [options.time] How long to run the collector for in milliseconds
-   * @param {number} [options.idle] How long to stop the collector after inactivity in milliseconds
+   * Options used to reset timeout and idle timer of a {@link Collector}.
+   * @typedef {Object} CollectorResetTimerOptions
+   * @property {number} [time] How long to run the collector for (in milliseconds)
+   * @property {number} [idle] How long to wait to stop the collector after inactivity (in milliseconds)
+   */
+
+  /**
+   * Resets the collector's timeout and idle timer.
+   * @param {CollectorResetTimerOptions} [options] Options for reseting
+
    */
   resetTimer({ time, idle } = {}) {
     if (this._timeout) {