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/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}
      */
 
     /**

src/structures/Message.js

@@ -284,9 +284,9 @@ class Message extends Base {
     /**
      * Reference data sent in a message that contains ids identifying the referenced message
      * @typedef {Object} MessageReference
-     * @property {string} channelId The channel's id the message was referenced
-     * @property {?string} guildId The guild's id the message was referenced
-     * @property {?string} messageId The message's id that was referenced
+     * @property {Snowflake} channelId The channel's id the message was referenced
+     * @property {?Snowflake} guildId The guild's id the message was referenced
+     * @property {?Snowflake} messageId The message's id that was referenced
      */
 
     if ('message_reference' in data || !partial) {

src/structures/MessageEmbed.js

@@ -44,13 +44,14 @@ class MessageEmbed {
   setup(data, skipValidation) {
     /**
      * The type of this embed, either:
-     * * `rich` - a rich embed
+     * * `rich` - a generic embed rendered from embed attributes
      * * `image` - an image embed
      * * `video` - a video embed
-     * * `gifv` - a gifv embed
+     * * `gifv` - an animated gif image embed rendered as a video embed
      * * `article` - an article embed
      * * `link` - a link embed
      * @type {string}
+     * @see {@link https://discord.com/developers/docs/resources/channel#embed-object-embed-types}
      * @deprecated
      */
     this.type = data.type ?? 'rich';
@@ -430,7 +431,7 @@ class MessageEmbed {
   }
 
   /**
-   * Normalizes field input and resolves strings.
+   * Normalizes field input and verifies strings.
    * @param {string} name The name of the field
    * @param {string} value The value of the field
    * @param {boolean} [inline=false] Set the field to display inline

src/structures/MessageMentions.js

@@ -96,9 +96,9 @@ class MessageMentions {
     /**
      * Crossposted channel data.
      * @typedef {Object} CrosspostedChannel
-     * @property {string} channelId The mentioned channel's id
-     * @property {string} guildId The id of the guild that has the channel
-     * @property {string} type The channel's type
+     * @property {Snowflake} channelId The mentioned channel's id
+     * @property {Snowflake} guildId The id of the guild that has the channel
+     * @property {ChannelType} type The channel's type
      * @property {string} name The channel's name
      */
 

src/structures/MessagePayload.js

@@ -49,7 +49,7 @@ class MessagePayload {
   }
 
   /**
-   * Whether or not the target is a webhook
+   * Whether or not the target is a {@link Webhook} or a {@link WebhookClient}
    * @type {boolean}
    * @readonly
    */
@@ -60,7 +60,7 @@ class MessagePayload {
   }
 
   /**
-   * Whether or not the target is a user
+   * Whether or not the target is a {@link User}
    * @type {boolean}
    * @readonly
    */
@@ -71,7 +71,7 @@ class MessagePayload {
   }
 
   /**
-   * Whether or not the target is a message
+   * Whether or not the target is a {@link Message}
    * @type {boolean}
    * @readonly
    */
@@ -81,7 +81,7 @@ class MessagePayload {
   }
 
   /**
-   * Wether or not the target is a message manager
+   * Wether or not the target is a {@link MessageManager}
    * @type {boolean}
    * @readonly
    */
@@ -91,7 +91,7 @@ class MessagePayload {
   }
 
   /**
-   * Whether or not the target is an interaction
+   * Whether or not the target is an {@link Interaction} or an {@link InteractionWebhook}
    * @type {boolean}
    * @readonly
    */
@@ -242,7 +242,7 @@ class MessagePayload {
   }
 
   /**
-   * Creates a `MessagePayload` from user-level arguments.
+   * Creates a {@link MessagePayload} from user-level arguments.
    * @param {MessageTarget} target Target to send to
    * @param {string|MessageOptions|WebhookMessageOptions} options Options or content to use
    * @param {MessageOptions|WebhookMessageOptions} [extra={}] - Extra options to add onto specified options

src/structures/MessageReaction.js

@@ -71,7 +71,7 @@ class MessageReaction {
   }
 
   /**
-   * The emoji of this reaction, either an GuildEmoji object for known custom emojis, or a ReactionEmoji
+   * The emoji of this reaction. Either a {@link GuildEmoji} object for known custom emojis, or a {@link ReactionEmoji}
    * object which has fewer properties. Whatever the prototype of the emoji, it will still have
    * `name`, `id`, `identifier` and `toString()`
    * @type {GuildEmoji|ReactionEmoji}

src/structures/PermissionOverwrites.js

@@ -135,14 +135,16 @@ class PermissionOverwrites extends Base {
   /**
    * The raw data for a permission overwrite
    * @typedef {Object} RawOverwriteData
-   * @property {Snowflake} id The id of the overwrite
+   * @property {Snowflake} id The id of the {@link Role} or {@link User} this overwrite belongs to
    * @property {string} allow The permissions to allow
    * @property {string} deny The permissions to deny
    * @property {number} type The type of this OverwriteData
    */
 
   /**
-   * Data that can be resolved into {@link RawOverwriteData}
+   * Data that can be resolved into {@link RawOverwriteData}. This can be:
+   * * PermissionOverwrites
+   * * OverwriteData
    * @typedef {PermissionOverwrites|OverwriteData} OverwriteResolvable
    */
 

src/structures/Presence.js

@@ -187,11 +187,16 @@ class Activity {
     this.applicationId = data.application_id ?? null;
 
     /**
-     * Timestamps for the activity
-     * @type {?Object}
+     * Represents timestamps of an activity
+     * @typedef {Object} ActivityTimestamps
      * @property {?Date} start When the activity started
      * @property {?Date} end When the activity will end
      */
+
+    /**
+     * Timestamps for the activity
+     * @type {?ActivityTimestamps}
+     */
     this.timestamps = data.timestamps
       ? {
           start: data.timestamps.start ? new Date(Number(data.timestamps.start)) : null,
@@ -212,11 +217,16 @@ class Activity {
     this.platform = data.platform ?? null;
 
     /**
-     * Party of the activity
-     * @type {?Object}
+     * Represents a party of an activity
+     * @typedef {Object} ActivityParty
      * @property {?string} id The party's id
      * @property {number[]} size Size of the party as `[current, max]`
      */
+
+    /**
+     * Party of the activity
+     * @type {?ActivityParty}
+     */
     this.party = data.party ?? null;
 
     /**
@@ -330,7 +340,7 @@ class RichPresenceAssets {
   /**
    * Gets the URL of the small image asset
    * @param {StaticImageURLOptions} [options] Options for the image url
-   * @returns {?string} The small image URL
+   * @returns {?string}
    */
   smallImageURL({ format, size } = {}) {
     return (
@@ -345,7 +355,7 @@ class RichPresenceAssets {
   /**
    * Gets the URL of the large image asset
    * @param {StaticImageURLOptions} [options] Options for the image url
-   * @returns {?string} The large image URL
+   * @returns {?string}
    */
   largeImageURL({ format, size } = {}) {
     if (!this.largeImage) return null;

src/structures/Team.js

@@ -82,7 +82,7 @@ class Team extends Base {
   /**
    * A link to the teams's icon.
    * @param {StaticImageURLOptions} [options={}] Options for the Image URL
-   * @returns {?string} URL to the icon
+   * @returns {?string}
    */
   iconURL({ format, size } = {}) {
     if (!this.icon) return null;

src/structures/ThreadChannel.js

@@ -237,7 +237,8 @@ class ThreadChannel extends Channel {
   }
 
   /**
-   * Fetches the owner of this thread
+   * Fetches the owner of this thread. If the thread member object isn't needed,
+   * use {@link ThreadChannel#ownerId} instead.
    * @param {FetchOwnerOptions} [options] The options for fetching the member
    * @returns {Promise<?ThreadMember>}
    */

src/structures/VoiceState.js

@@ -58,7 +58,7 @@ class VoiceState extends Base {
      */
     this.sessionId = data.session_id ?? null;
     /**
-     * Whether this member is streaming using "Go Live"
+     * Whether this member is streaming using "Screen Share"
      * @type {boolean}
      */
     this.streaming = data.self_stream ?? false;

src/structures/interfaces/Application.js

@@ -63,7 +63,7 @@ class Application extends Base {
   /**
    * A link to the application's icon.
    * @param {StaticImageURLOptions} [options={}] Options for the Image URL
-   * @returns {?string} URL to the icon
+   * @returns {?string}
    */
   iconURL({ format, size } = {}) {
     if (!this.icon) return null;
@@ -73,7 +73,7 @@ class Application extends Base {
   /**
    * A link to this application's cover image.
    * @param {StaticImageURLOptions} [options={}] Options for the Image URL
-   * @returns {?string} URL to the cover image
+   * @returns {?string}
    */
   coverURL({ format, size } = {}) {
     if (!this.cover) return null;