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/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,7 +339,7 @@ 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 }) {
@@ -346,11 +347,10 @@ class GuildMemberManager extends CachedManager {
   }
 
   /**
-   * 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