docs: Use info blocks for requirements (#8361)

2026-03-11 17:13:31 +01:00 · 2022-07-27 11:09:50 +01:00
parent 5d8bd030d6
commit 80b9738957
13 changed files with 50 additions and 41 deletions
--- a/packages/discord.js/src/client/actions/InviteCreate.js
+++ b/packages/discord.js/src/client/actions/InviteCreate.js
@@ -15,8 +15,8 @@ class InviteCreateAction extends Action {

    /**
     * Emitted when an invite is created.
-     * <info> This event only triggers if the client has {@link PermissionFlagsBits.ManageGuild} permissions
-     * for the guild, or {@link PermissionFlagsBits.ManageChannels} permissions for the channel.</info>
+     * <info>This event requires either the {@link PermissionFlagsBits.ManageGuild} permission or the
+     * {@link PermissionFlagsBits.ManageChannels} permission for the channel.</info>
     * @event Client#inviteCreate
     * @param {Invite} invite The invite that was created
     */
--- a/packages/discord.js/src/client/actions/InviteDelete.js
+++ b/packages/discord.js/src/client/actions/InviteDelete.js
@@ -17,8 +17,8 @@ class InviteDeleteAction extends Action {

    /**
     * Emitted when an invite is deleted.
-     * <info> This event only triggers if the client has {@link PermissionFlagsBits.ManageGuild} permissions
-     * for the guild, or `{@link PermissionFlagsBits.ManageChannels}` permissions for the channel.</info>
+     * <info>This event requires either the {@link PermissionFlagsBits.ManageGuild} permission or the
+     * {@link PermissionFlagsBits.ManageChannels} permission for the channel.</info>
     * @event Client#inviteDelete
     * @param {Invite} invite The invite that was deleted
     */
--- a/packages/discord.js/src/client/actions/ThreadMembersUpdate.js
+++ b/packages/discord.js/src/client/actions/ThreadMembersUpdate.js
@@ -31,8 +31,8 @@ class ThreadMembersUpdateAction extends Action {
      }

      /**
-       * Emitted whenever members are added or removed from a thread. Requires
-       * {@link GatewayIntentBits.GuildMembers} privileged intent
+       * Emitted whenever members are added or removed from a thread.
+       * <info>This event requires the {@link GatewayIntentBits.GuildMembers} privileged gateway intent.</info>
       * @event Client#threadMembersUpdate
       * @param {Collection<Snowflake, ThreadMember>} addedMembers The members that were added
       * @param {Collection<Snowflake, ThreadMember>} removedMembers The members that were removed
--- a/packages/discord.js/src/managers/GuildMemberManager.js
+++ b/packages/discord.js/src/managers/GuildMemberManager.js
@@ -74,20 +74,23 @@ class GuildMemberManager extends CachedManager {
  /**
   * 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
-   * @property {string} [nick] The nickname to give to the member (requires {@link PermissionFlagsBits.ManageNicknames})
+   * @property {string} accessToken An OAuth2 access token for the user with the {@link OAuth2Scopes.GuildsJoin}
+   * scope granted to the bot's application
+   * @property {string} [nick] The nickname to give to the member
+   * <info>This property requires the {@link PermissionFlagsBits.ManageNicknames} permission.</info>
   * @property {Collection<Snowflake, Role>|RoleResolvable[]} [roles] The roles to add to the member
-   * (requires {@link PermissionFlagsBits.ManageRoles})
-   * @property {boolean} [mute] Whether the member should be muted (requires {@link PermissionFlagsBits.MuteMembers})
+   * <info>This property requires the {@link PermissionFlagsBits.ManageRoles} permission.</info>
+   * @property {boolean} [mute] Whether the member should be muted
+   * <info>This property requires the {@link PermissionFlagsBits.MuteMembers} permission.</info>
   * @property {boolean} [deaf] Whether the member should be deafened
-   * (requires {@link PermissionFlagsBits.DeafenMembers})
-   * @property {boolean} [force] Whether to skip the cache check and call the API directly
+   * <info>This property requires the {@link PermissionFlagsBits.MuteMembers} permission.</info>
+   * @property {boolean} [force] Whether to skip the cache check and request the API directly
   * @property {boolean} [fetchWhenExisting=true] Whether to fetch the user if not cached and already a member
   */

  /**
-   * Adds a user to the guild using OAuth2. Requires the {@link PermissionFlagsBits.CreateInstantInvite} permission.
+   * Adds a user to the guild using OAuth2.
+   * <info>This method requires the {@link PermissionFlagsBits.CreateInstantInvite} 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|null>}
--- a/packages/discord.js/src/managers/ThreadManager.js
+++ b/packages/discord.js/src/managers/ThreadManager.js
@@ -177,11 +177,12 @@ class ThreadManager extends CachedManager {
  /**
   * The options used to fetch archived threads.
   * @typedef {Object} FetchArchivedThreadOptions
-   * @property {string} [type='public'] The type of threads to fetch, either `public` or `private`
-   * @property {boolean} [fetchAll=false] Whether to fetch **all** archived threads when type is `private`.
-   * Requires {@link PermissionFlagsBits.ManageThreads} if true
+   * @property {string} [type='public'] The type of threads to fetch (`public` or `private`)
+   * @property {boolean} [fetchAll=false] Whether to fetch **all** archived threads when `type` is `private`
+   * <info>This property requires the {@link PermissionFlagsBits.ManageThreads} permission if `true`.</info>
   * @property {DateResolvable|ThreadChannelResolvable} [before] Only return threads that were created before this Date
-   * or Snowflake. <warn>Must be a {@link ThreadChannelResolvable} when type is `private` and fetchAll is `false`</warn>
+   * or Snowflake
+   * <warn>Must be a {@link ThreadChannelResolvable} when `type` is `private` and `fetchAll` is `false`.</warn>
   * @property {number} [limit] Maximum number of threads to return
   */

@@ -193,8 +194,9 @@ class ThreadManager extends CachedManager {
   */

  /**
-   * Obtains a set of archived threads from Discord, requires {@link PermissionFlagsBits.ReadMessageHistory}
-   * in the parent channel.
+   * Obtains a set of archived threads from Discord.
+   * <info>This method requires the {@link PermissionFlagsBits.ReadMessageHistory} permission
+   * in the parent channel.</info>
   * @param {FetchArchivedThreadOptions} [options] The options to fetch archived threads
   * @param {boolean} [cache=true] Whether to cache the new thread objects if they aren't already
   * @returns {Promise<FetchedThreads>}
@@ -232,8 +234,9 @@ class ThreadManager extends CachedManager {
  }

  /**
-   * Obtains the accessible active threads from Discord, requires {@link PermissionFlagsBits.ReadMessageHistory}
-   * in the parent channel.
+   * Obtains the accessible active threads from Discord.
+   * <info>This method requires the {@link PermissionFlagsBits.ReadMessageHistory} permission
+   * in the parent channel.</info>
   * @param {boolean} [cache=true] Whether to cache the new thread objects if they aren't already
   * @returns {Promise<FetchedThreads>}
   */
--- a/packages/discord.js/src/managers/ThreadMemberManager.js
+++ b/packages/discord.js/src/managers/ThreadMemberManager.js
@@ -122,7 +122,8 @@ class ThreadMemberManager extends CachedManager {
   */

  /**
-   * Fetches thread member(s) from Discord. Requires the {@link GatewayIntentBits.GuildMembers} gateway intent.
+   * Fetches thread member(s) from Discord.
+   * <info>This method requires the {@link GatewayIntentBits.GuildMembers} privileged gateway intent.</info>
   * @param {ThreadMemberResolvable|FetchThreadMemberOptions|FetchThreadMembersOptions} [options]
   * Options for fetching thread member(s)
   * @returns {Promise<ThreadMember|Collection<Snowflake, ThreadMember>>}
--- a/packages/discord.js/src/structures/GuildChannel.js
+++ b/packages/discord.js/src/structures/GuildChannel.js
@@ -151,7 +151,7 @@ class GuildChannel extends BaseChannel {
  /**
   * Gets the overall set of permissions for a member or role in this channel, taking into account channel overwrites.
   * @param {GuildMemberResolvable|RoleResolvable} memberOrRole The member or role to obtain the overall permissions for
-   * @param {boolean} [checkAdmin=true] Whether having {@link PermissionFlagsBits.Administrator}
+   * @param {boolean} [checkAdmin=true] Whether having the {@link PermissionFlagsBits.Administrator} permission
   * will return all permissions
   * @returns {?Readonly<PermissionsBitField>}
   */
@@ -191,7 +191,7 @@ class GuildChannel extends BaseChannel {
  /**
   * Gets the overall set of permissions for a member in this channel, taking into account channel overwrites.
   * @param {GuildMember} member The member to obtain the overall permissions for
-   * @param {boolean} checkAdmin=true Whether having {@link PermissionFlagsBits.Administrator}
+   * @param {boolean} checkAdmin Whether having the {@link PermissionFlagsBits.Administrator} permission
   * will return all permissions
   * @returns {Readonly<PermissionsBitField>}
   * @private
@@ -223,7 +223,8 @@ class GuildChannel extends BaseChannel {
  /**
   * Gets the overall set of permissions for a role in this channel, taking into account channel overwrites.
   * @param {Role} role The role to obtain the overall permissions for
-   * @param {boolean} checkAdmin Whether having {@link PermissionFlagsBits.Administrator} will return all permissions
+   * @param {boolean} checkAdmin Whether having the {@link PermissionFlagsBits.Administrator} permission
+   * will return all permissions
   * @returns {Readonly<PermissionsBitField>}
   * @private
   */
--- a/packages/discord.js/src/structures/Message.js
+++ b/packages/discord.js/src/structures/Message.js
@@ -641,8 +641,8 @@ class Message extends Base {
   * @property {?string} [content] Content to be edited
   * @property {Embed[]|APIEmbed[]} [embeds] Embeds to be added/edited
   * @property {MessageMentionOptions} [allowedMentions] Which mentions should be parsed from the message content
-   * @property {MessageFlags} [flags] Which flags to set for the message.
-   * Only {@link MessageFlags.SuppressEmbeds} can be edited.
+   * @property {MessageFlags} [flags] Which flags to set for the message
+   * <info>Only the {@link MessageFlags.SuppressEmbeds} flag can be modified.</info>
   * @property {Attachment[]} [attachments] An array of attachments to keep,
   * all attachments will be kept if omitted
   * @property {Array<JSONEncodable<AttachmentPayload>>|BufferResolvable[]|Attachment[]|AttachmentBuilder[]} [files]
--- a/packages/discord.js/src/structures/Presence.js
+++ b/packages/discord.js/src/structures/Presence.js
@@ -268,7 +268,7 @@ class Activity {
  }

  /**
-   * When concatenated with a string, this automatically returns the activities' name instead of the Activity object.
+   * When concatenated with a string, this automatically returns the activity's name instead of the Activity object.
   * @returns {string}
   */
  toString() {
--- a/packages/discord.js/src/structures/Role.js
+++ b/packages/discord.js/src/structures/Role.js
@@ -223,7 +223,7 @@ class Role extends Base {
   * Returns `channel.permissionsFor(role)`. Returns permissions for a role in a guild channel,
   * taking into account permission overwrites.
   * @param {GuildChannel|Snowflake} channel The guild channel to use as context
-   * @param {boolean} [checkAdmin=true] Whether having {@link PermissionFlagsBits.Administrator}
+   * @param {boolean} [checkAdmin=true] Whether having the {@link PermissionFlagsBits.Administrator} permission
   * will return all permissions
   * @returns {Readonly<PermissionsBitField>}
   */
--- a/packages/discord.js/src/structures/ThreadChannel.js
+++ b/packages/discord.js/src/structures/ThreadChannel.js
@@ -75,9 +75,9 @@ class ThreadChannel extends BaseChannel {
      this.locked = data.thread_metadata.locked ?? false;

      /**
-       * Whether members without {@link PermissionFlagsBits.ManageThreads} can invite other members without
-       * {@link PermissionFlagsBits.ManageThreads}
-       * <info>Always `null` in public threads</info>
+       * Whether members without the {@link PermissionFlagsBits.ManageThreads} permission
+       * can invite other members to this thread.
+       * <info>This property is always `null` in public threads.</info>
       * @type {?boolean}
       */
      this.invitable = this.type === ChannelType.GuildPrivateThread ? data.thread_metadata.invitable ?? false : null;
@@ -253,7 +253,7 @@ class ThreadChannel extends BaseChannel {
   * Gets the overall set of permissions for a member or role in this thread's parent channel, taking overwrites into
   * account.
   * @param {GuildMemberResolvable|RoleResolvable} memberOrRole The member or role to obtain the overall permissions for
-   * @param {boolean} [checkAdmin=true] Whether having {@link PermissionFlagsBits.Administrator}
+   * @param {boolean} [checkAdmin=true] Whether having the {@link PermissionFlagsBits.Administrator} permission
   * will return all permissions
   * @returns {?Readonly<PermissionsBitField>}
   */
@@ -363,8 +363,8 @@ class ThreadChannel extends BaseChannel {
  }

  /**
-   * Sets whether members without the {@link PermissionFlagsBits.ManageThreads} permission can invite other members
-   * without the {@link PermissionFlagsBits.ManageThreads} permission to this thread.
+   * Sets whether members without the {@link PermissionFlagsBits.ManageThreads} permission
+   * can invite other members to this thread.
   * @param {boolean} [invitable=true] Whether non-moderators can invite non-moderators to this thread
   * @param {string} [reason] Reason for changing invite
   * @returns {Promise<ThreadChannel>}
@@ -377,8 +377,9 @@ class ThreadChannel extends BaseChannel {
  }

  /**
-   * Sets whether the thread can be **unarchived** by anyone with {@link PermissionFlagsBits.SendMessages} permission.
-   * When a thread is locked only members with {@link PermissionFlagsBits.ManageThreads} can unarchive it.
+   * Sets whether the thread can be **unarchived** by anyone with the
+   * {@link PermissionFlagsBits.SendMessages} permission. When a thread is locked, only members with the
+   * {@link PermissionFlagsBits.ManageThreads} permission can unarchive it.
   * @param {boolean} [locked=true] Whether the thread is locked
   * @param {string} [reason] Reason for locking or unlocking the thread
   * @returns {Promise<ThreadChannel>}
--- a/packages/discord.js/src/structures/Webhook.js
+++ b/packages/discord.js/src/structures/Webhook.js
@@ -128,7 +128,7 @@ class Webhook {
   * @property {Snowflake} [threadId] The id of the thread in the channel to send to.
   * <info>For interaction webhooks, this property is ignored</info>
   * @property {MessageFlags} [flags] Which flags to set for the message.
-   * Only {@link MessageFlags.SuppressEmbeds} can be set.
+   * <info>Only the {@link MessageFlags.SuppressEmbeds} flag can be set.</info>
   */

  /**
--- a/packages/discord.js/src/util/Options.js
+++ b/packages/discord.js/src/util/Options.js
@@ -33,8 +33,8 @@ const { toSnakeCase } = require('./Transformers');
 * @property {boolean} [failIfNotExists=true] Default value for {@link ReplyMessageOptions#failIfNotExists}
 * @property {PresenceData} [presence={}] Presence data to use upon login
 * @property {IntentsResolvable} intents Intents to enable for this connection
- * @property {number} [waitGuildTimeout=15_000] Time in milliseconds that Clients with the GUILDS intent should wait for
- * missing guilds to be received before starting the bot. If not specified, the default is 15 seconds.
+ * @property {number} [waitGuildTimeout=15_000] Time in milliseconds that clients with the
+ * {@link GatewayIntentBits.Guilds} gateway intent should wait for missing guilds to be received before being ready.
 * @property {SweeperOptions} [sweepers={}] Options for cache sweeping
 * @property {WebsocketOptions} [ws] Options for the WebSocket
 * @property {RESTOptions} [rest] Options for the REST manager