docs(*): add links to Discord's API objects & data (#5862)

src/managers/ApplicationCommandManager.js

@@ -193,7 +193,7 @@ class ApplicationCommandManager extends BaseManager {
   /**
    * Transforms an {@link ApplicationCommandData} object into something that can be used with the API.
    * @param {ApplicationCommandData} command The command to transform
-   * @returns {Object}
+   * @returns {APIApplicationCommand}
    * @private
    */
   static transformCommand(command) {
@@ -326,7 +326,7 @@ class ApplicationCommandManager extends BaseManager {
    * Transforms an {@link ApplicationCommandPermissionData} object into something that can be used with the API.
    * @param {ApplicationCommandPermissionData} permissions The permissions to transform
    * @param {boolean} [received] Whether these permissions have been received from Discord
-   * @returns {Object}
+   * @returns {APIApplicationCommandPermissions}
    * @private
    */
   static transformPermissions(permissions, received) {
@@ -342,3 +342,8 @@ class ApplicationCommandManager extends BaseManager {
 }
 
 module.exports = ApplicationCommandManager;
+
+/**
+ * @external APIApplicationCommandPermissions
+ * @see {@link https://discord.com/developers/docs/interactions/slash-commands#applicationcommandpermissions}
+ */

src/rest/DiscordAPIError.js

@@ -47,7 +47,7 @@ class DiscordAPIError extends Error {
 
   /**
    * Flattens an errors object returned from the API into an array.
-   * @param {Object} obj Discord errors object
+   * @param {APIError} obj Discord errors object
    * @param {string} [key] Used internally to determine key names of nested fields
    * @returns {string[]}
    * @private
@@ -75,3 +75,8 @@ class DiscordAPIError extends Error {
 }
 
 module.exports = DiscordAPIError;
+
+/**
+ * @external APIError
+ * @see {@link https://discord.com/developers/docs/reference#error-messages}
+ */

src/structures/APIMessage.js

@@ -31,13 +31,20 @@ class APIMessage {
 
     /**
      * Data sendable to the API
-     * @type {?Object}
+     * @type {?APIMessageRaw}
      */
     this.data = null;
 
+    /**
+     * @typedef {Object} MessageFile
+     * @property {Buffer|string|Stream} attachment The original attachment that generated this file
+     * @property {string} name The name of this file
+     * @property {Buffer|Stream} file The file to be sent to the API
+     */
+
     /**
      * Files sendable to the API
-     * @type {?Object[]}
+     * @type {?MessageFile[]}
      */
     this.files = null;
   }
@@ -259,7 +266,7 @@ class APIMessage {
   /**
    * Resolves a single file into an object sendable to the API.
    * @param {BufferResolvable|Stream|FileOptions|MessageAttachment} fileLike Something that could be resolved to a file
-   * @returns {Object}
+   * @returns {MessageFile}
    */
   static async resolveFile(fileLike) {
     let attachment;
@@ -313,3 +320,8 @@ module.exports = APIMessage;
  * @typedef {TextChannel|DMChannel|User|GuildMember|Webhook|WebhookClient|Interaction|InteractionWebhook|
  * Message|MessageManager} MessageTarget
  */
+
+/**
+ * @external APIMessageRaw
+ * @see {@link https://discord.com/developers/docs/resources/channel#message-object}
+ */

src/structures/ApplicationCommand.js

@@ -206,13 +206,13 @@ class ApplicationCommand extends Base {
    * Transforms an {@link ApplicationCommandOptionData} object into something that can be used with the API.
    * @param {ApplicationCommandOptionData} option The option to transform
    * @param {boolean} [received] Whether this option has been received from Discord
-   * @returns {Object}
+   * @returns {APIApplicationCommandOption}
    * @private
    */
   static transformOption(option, received) {
     const stringType = typeof option.type === 'string' ? option.type : ApplicationCommandOptionTypes[option.type];
     return {
-      type: typeof option.type === 'number' && !received ? option.type : ApplicationCommandOptionTypes[option.type],
+      type: typeof option.type === 'number' && !received ? option.type : stringType,
       name: option.name,
       description: option.description,
       required:
@@ -224,3 +224,13 @@ class ApplicationCommand extends Base {
 }
 
 module.exports = ApplicationCommand;
+
+/**
+ * @external APIApplicationCommand
+ * @see {@link https://discord.com/developers/docs/interactions/slash-commands#applicationcommand}
+ */
+
+/**
+ * @external APIApplicationCommandOption
+ * @see {@link https://discord.com/developers/docs/interactions/slash-commands#applicationcommandoption}
+ */

src/structures/Channel.js

@@ -165,3 +165,8 @@ class Channel extends Base {
 }
 
 module.exports = Channel;
+
+/**
+ * @external APIChannel
+ * @see {@link https://discord.com/developers/docs/resources/channel#channel-object}
+ */

src/structures/ClientPresence.js

@@ -7,7 +7,7 @@ const { ActivityTypes, OPCodes } = require('../util/Constants');
 class ClientPresence extends Presence {
   /**
    * @param {Client} client The instantiating client
-   * @param {Object} [data={}] The data for the client presence
+   * @param {APIPresence} [data={}] The data for the client presence
    */
   constructor(client, data = {}) {
     super(client, Object.assign(data, { status: data.status || 'online', user: { id: null } }));

src/structures/ClientUser.js

@@ -48,7 +48,7 @@ class ClientUser extends Structures.get('User') {
 
   /**
    * Edits the logged in client.
-   * @param {Object} data The new data
+   * @param {APIModifyClientData} data The new data
    * @param {string} [data.username] The new username
    * @param {BufferResolvable|Base64Resolvable} [data.avatar] The new avatar
    */
@@ -143,8 +143,7 @@ class ClientUser extends Structures.get('User') {
 
   /**
    * Options for setting an activity.
-   * @typedef ActivityOptions
-   * @type {Object}
+   * @typedef {Object} ActivityOptions
    * @property {string} [name] Name of the activity
    * @property {string} [url] Twitch / YouTube stream URL
    * @property {ActivityType|number} [type] Type of the activity
@@ -179,3 +178,8 @@ class ClientUser extends Structures.get('User') {
 }
 
 module.exports = ClientUser;
+
+/**
+ * @external APIModifyClientData
+ * @see {@link https://discord.com/developers/docs/resources/user#modify-current-user-json-params}
+ */

src/structures/CommandInteraction.js

@@ -89,15 +89,15 @@ class CommandInteraction extends Interaction {
    * @property {Collection<string, CommandInteractionOption>} [options] Additional options if this option is a
    * subcommand (group)
    * @property {User} [user] The resolved user
-   * @property {GuildMember|Object} [member] The resolved member
-   * @property {GuildChannel|Object} [channel] The resolved channel
-   * @property {Role|Object} [role] The resolved role
+   * @property {GuildMember|APIGuildMember} [member] The resolved member
+   * @property {GuildChannel|APIChannel} [channel] The resolved channel
+   * @property {Role|APIRole} [role] The resolved role
    */
 
   /**
    * Transforms an option received from the API.
-   * @param {Object} option The received option
-   * @param {Object} resolved The resolved interaction data
+   * @param {APIApplicationCommandOption} option The received option
+   * @param {APIApplicationCommandOptionResolved} resolved The resolved interaction data
    * @returns {CommandInteractionOption}
    * @private
    */
@@ -127,8 +127,8 @@ class CommandInteraction extends Interaction {
 
   /**
    * Creates a collection of options from the received options array.
-   * @param {Object[]} options The received options
-   * @param {Object} resolved The resolved interaction data
+   * @param {APIApplicationCommandOption[]} options The received options
+   * @param {APIApplicationCommandOptionResolved} resolved The resolved interaction data
    * @returns {Collection<string, CommandInteractionOption>}
    * @private
    */
@@ -154,3 +154,9 @@ class CommandInteraction extends Interaction {
 InteractionResponses.applyToClass(CommandInteraction, ['deferUpdate', 'update']);
 
 module.exports = CommandInteraction;
+
+/* eslint-disable max-len */
+/**
+ * @external APIApplicationCommandOptionResolved
+ * @see {@link https://discord.com/developers/docs/interactions/slash-commands#interaction-applicationcommandinteractiondataresolved}
+ */

src/structures/DMChannel.js

@@ -12,7 +12,7 @@ const MessageManager = require('../managers/MessageManager');
 class DMChannel extends Channel {
   /**
    * @param {Client} client The instantiating client
-   * @param {Object} data The data for the DM channel
+   * @param {APIChannel} data The data for the DM channel
    */
   constructor(client, data) {
     super(client, data);

src/structures/Emoji.js

@@ -5,7 +5,7 @@ const SnowflakeUtil = require('../util/SnowflakeUtil');
 
 /**
  * Represents raw emoji data from the API
- * @typedef {Object} RawEmoji
+ * @typedef {APIEmoji} RawEmoji
  * @property {?Snowflake} id ID of this emoji
  * @property {?string} name Name of this emoji
  * @property {?boolean} animated Whether this emoji is animated
@@ -110,3 +110,8 @@ class Emoji extends Base {
 }
 
 module.exports = Emoji;
+
+/**
+ * @external APIEmoji
+ * @see {@link https://discord.com/developers/docs/resources/emoji#emoji-object}
+ */

src/structures/Guild.js

@@ -1389,3 +1389,8 @@ class Guild extends AnonymousGuild {
 }
 
 module.exports = Guild;
+
+/**
+ * @external APIGuild
+ * @see {@link https://discord.com/developers/docs/resources/guild#guild-object}
+ */

src/structures/GuildBan.js

@@ -9,7 +9,7 @@ const Base = require('./Base');
 class GuildBan extends Base {
   /**
    * @param {Client} client The instantiating client
-   * @param {Object} data The data for the ban
+   * @param {APIBanData} data The data for the ban
    * @param {Guild} guild The guild in which the ban is
    */
   constructor(client, data, guild) {
@@ -61,3 +61,8 @@ class GuildBan extends Base {
 }
 
 module.exports = GuildBan;
+
+/**
+ * @external APIBanData
+ * @see {@link https://discord.com/developers/docs/resources/guild#create-guild-ban-json-params}
+ */

src/structures/GuildChannel.js

@@ -25,7 +25,7 @@ const Util = require('../util/Util');
 class GuildChannel extends Channel {
   /**
    * @param {Guild} guild The guild the guild channel is part of
-   * @param {Object} data The data for the guild channel
+   * @param {APIChannel} data The data for the guild channel
    */
   constructor(guild, data) {
     super(guild.client, data);

src/structures/GuildEmoji.js

@@ -12,7 +12,7 @@ const Permissions = require('../util/Permissions');
 class GuildEmoji extends BaseGuildEmoji {
   /**
    * @param {Client} client The instantiating client
-   * @param {Object} data The data for the guild emoji
+   * @param {APIEmoji} data The data for the guild emoji
    * @param {Guild} guild The guild the guild emoji is part of
    */
   constructor(client, data, guild) {
@@ -151,7 +151,7 @@ class GuildEmoji extends BaseGuildEmoji {
 
   /**
    * Whether this emoji is the same as another one.
-   * @param {GuildEmoji|Object} other The emoji to compare it to
+   * @param {GuildEmoji|APIEmoji} other The emoji to compare it to
    * @returns {boolean} Whether the emoji is equal to the given emoji or not
    */
   equals(other) {

src/structures/GuildMember.js

@@ -15,7 +15,7 @@ let Structures;
 class GuildMember extends Base {
   /**
    * @param {Client} client The instantiating client
-   * @param {Object} data The data for the guild member
+   * @param {APIGuildMember} data The data for the guild member
    * @param {Guild} guild The guild the member is part of
    */
   constructor(client, data, guild) {
@@ -397,3 +397,8 @@ class GuildMember extends Base {
 TextBasedChannel.applyToClass(GuildMember);
 
 module.exports = GuildMember;
+
+/**
+ * @external APIGuildMember
+ * @see {@link https://discord.com/developers/docs/resources/guild#guild-member-object}
+ */

src/structures/GuildTemplate.js

@@ -11,7 +11,7 @@ const DataResolver = require('../util/DataResolver');
 class GuildTemplate extends Base {
   /**
    * @param {Client} client The instantiating client
-   * @param {Object} data The raw data for the template
+   * @param {APIGuildTemplate} data The raw data for the template
    */
   constructor(client, data) {
     super(client);
@@ -20,7 +20,7 @@ class GuildTemplate extends Base {
 
   /**
    * Builds or updates the template with the provided data.
-   * @param {Object} data The raw data for the template
+   * @param {APIGuildTemplate} data The raw data for the template
    * @returns {GuildTemplate}
    * @private
    */
@@ -81,8 +81,7 @@ class GuildTemplate extends Base {
 
     /**
      * The data of the guild that this template would create
-     * @type {Object}
-     * @see {@link https://discord.com/developers/docs/resources/guild#guild-resource}
+     * @type {APIGuild}
      */
     this.serializedGuild = data.serialized_source_guild;
 
@@ -234,3 +233,9 @@ class GuildTemplate extends Base {
 GuildTemplate.GUILD_TEMPLATES_PATTERN = /discord(?:app)?\.(?:com\/template|new)\/([\w-]{2,255})/gi;
 
 module.exports = GuildTemplate;
+
+/* eslint-disable max-len */
+/**
+ * @external APIGuildTemplate
+ * @see {@link https://discord.com/developers/docs/resources/guild-template#guild-template-object-guild-template-structure}
+ */

src/structures/Interaction.js

@@ -58,7 +58,7 @@ class Interaction extends Base {
 
     /**
      * If this interaction was sent in a guild, the member which sent it
-     * @type {?GuildMember|Object}
+     * @type {?GuildMember|APIGuildMember}
      */
     this.member = data.member ? this.guild?.members.add(data.member) ?? data.member : null;
 

src/structures/InteractionWebhook.js

@@ -29,7 +29,7 @@ class InteractionWebhook {
   /**
    * Sends a message with this webhook.
    * @param {string|APIMessage|InteractionReplyOptions} options The content for the reply
-   * @returns {Promise<Message|Object>}
+   * @returns {Promise<Message|APIMessageRaw>}
    */
   send() {}
   fetchMessage() {}

src/structures/Message.js

@@ -26,7 +26,7 @@ const Util = require('../util/Util');
 class Message extends Base {
   /**
    * @param {Client} client The instantiating client
-   * @param {Object} data The data for the message
+   * @param {APIMessageRaw} data The data for the message
    * @param {TextChannel|DMChannel|NewsChannel} channel The channel the message was sent in
    */
   constructor(client, data, channel) {
@@ -283,7 +283,7 @@ class Message extends Base {
 
   /**
    * Updates the message and returns the old message.
-   * @param {Object} data Raw Discord message update data
+   * @param {APIMessageRaw} data Raw Discord message update data
    * @returns {Message}
    * @private
    */
@@ -537,7 +537,7 @@ class Message extends Base {
    * Options that can be passed into {@link Message#edit}.
    * @typedef {Object} MessageEditOptions
    * @property {?string} [content] Content to be edited
-   * @property {MessageEmbed[]|Object[]} [embeds] Embeds to be added/edited
+   * @property {MessageEmbed[]|APIEmbed[]} [embeds] Embeds to be added/edited
    * @property {string|boolean} [code] Language for optional codeblock formatting to apply
    * @property {MessageMentionOptions} [allowedMentions] Which mentions should be parsed from the message content
    * @property {MessageFlags} [flags] Which flags to set for the message. Only `SUPPRESS_EMBEDS` can be edited.
@@ -724,7 +724,7 @@ class Message extends Base {
    * without checking all the properties, use `message.id === message2.id`, which is much more efficient. This
    * method allows you to see if there are differences in content, embeds, attachments, nonce and tts properties.
    * @param {Message} message The message to compare it to
-   * @param {Object} rawData Raw data passed through the WebSocket about this message
+   * @param {APIMessageRaw} rawData Raw data passed through the WebSocket about this message
    * @returns {boolean}
    */
   equals(message, rawData) {