refactor: improve the accuracy of docs/improve docs (#4845)

Co-authored-by: Noel <icrawltogo@gmail.com>

src/structures/Base.js

@@ -4,6 +4,7 @@ const Util = require('../util/Util');
 
 /**
  * Represents a data model that is identifiable by a Snowflake (i.e. Discord API data models).
+ * @abstract
  */
 class Base {
   constructor(client) {

src/structures/BaseGuildEmoji.js

@@ -5,6 +5,7 @@ const Emoji = require('./Emoji');
 /**
  * Parent class for {@link GuildEmoji} and {@link GuildPreviewEmoji}.
  * @extends {Emoji}
+ * @abstract
  */
 class BaseGuildEmoji extends Emoji {
   constructor(client, data, guild) {
@@ -16,6 +17,10 @@ class BaseGuildEmoji extends Emoji {
      */
     this.guild = guild;
 
+    this.requireColons = null;
+    this.managed = null;
+    this.available = null;
+
     /**
      * Array of role ids this emoji is active for
      * @name BaseGuildEmoji#_roles
@@ -30,26 +35,29 @@ class BaseGuildEmoji extends Emoji {
   _patch(data) {
     if (data.name) this.name = data.name;
 
-    /**
-     * Whether or not this emoji requires colons surrounding it
-     * @type {?boolean}
-     * @name GuildEmoji#requiresColons
-     */
-    if (typeof data.require_colons !== 'undefined') this.requiresColons = data.require_colons;
+    if (typeof data.require_colons !== 'undefined') {
+      /**
+       * Whether or not this emoji requires colons surrounding it
+       * @type {?boolean}
+       */
+      this.requiresColons = data.require_colons;
+    }
 
-    /**
-     * Whether this emoji is managed by an external service
-     * @type {?boolean}
-     * @name GuildEmoji#managed
-     */
-    if (typeof data.managed !== 'undefined') this.managed = data.managed;
+    if (typeof data.managed !== 'undefined') {
+      /**
+       * Whether this emoji is managed by an external service
+       * @type {?boolean}
+       */
+      this.managed = data.managed;
+    }
 
-    /**
-     * Whether this emoji is available
-     * @type {?boolean}
-     * @name GuildEmoji#available
-     */
-    if (typeof data.available !== 'undefined') this.available = data.available;
+    if (typeof data.available !== 'undefined') {
+      /**
+       * Whether this emoji is available
+       * @type {?boolean}
+       */
+      this.available = data.available;
+    }
 
     if (data.roles) this._roles = data.roles;
   }

src/structures/Channel.js

@@ -7,6 +7,7 @@ const Snowflake = require('../util/Snowflake');
 /**
  * Represents any channel on Discord.
  * @extends {Base}
+ * @abstract
  */
 class Channel extends Base {
   constructor(client, data) {

src/structures/Guild.js

@@ -231,36 +231,38 @@ class Guild extends Base {
      */
     this.premiumTier = data.premium_tier;
 
-    /**
-     * The total number of boosts for this server
-     * @type {?number}
-     * @name Guild#premiumSubscriptionCount
-     */
     if (typeof data.premium_subscription_count !== 'undefined') {
+      /**
+       * The total number of boosts for this server
+       * @type {?number}
+       */
       this.premiumSubscriptionCount = data.premium_subscription_count;
     }
 
-    /**
-     * Whether widget images are enabled on this guild
-     * @type {?boolean}
-     * @name Guild#widgetEnabled
-     */
-    if (typeof data.widget_enabled !== 'undefined') this.widgetEnabled = data.widget_enabled;
+    if (typeof data.widget_enabled !== 'undefined') {
+      /**
+       * Whether widget images are enabled on this guild
+       * @type {?boolean}
+       */
+      this.widgetEnabled = data.widget_enabled;
+    }
 
-    /**
-     * The widget channel ID, if enabled
-     * @type {?string}
-     * @name Guild#widgetChannelID
-     */
-    if (typeof data.widget_channel_id !== 'undefined') this.widgetChannelID = data.widget_channel_id;
+    if (typeof data.widget_channel_id !== 'undefined') {
+      /**
+       * The widget channel ID, if enabled
+       * @type {?string}
+       */
+      this.widgetChannelID = data.widget_channel_id;
+    }
 
-    /**
-     * The embed channel ID, if enabled
-     * @type {?string}
-     * @name Guild#embedChannelID
-     * @deprecated
-     */
-    if (typeof data.embed_channel_id !== 'undefined') this.embedChannelID = data.embed_channel_id;
+    if (typeof data.embed_channel_id !== 'undefined') {
+      /**
+       * The embed channel ID, if enabled
+       * @type {?string}
+       * @deprecated
+       */
+      this.embedChannelID = data.embed_channel_id;
+    }
 
     /**
      * The verification level of the guild
@@ -299,40 +301,47 @@ class Guild extends Base {
      */
     this.systemChannelFlags = new SystemChannelFlags(data.system_channel_flags).freeze();
 
-    /**
-     * The maximum amount of members the guild can have
-     * <info>You will need to fetch the guild using {@link Guild#fetch} if you want to receive this parameter</info>
-     * @type {?number}
-     * @name Guild#maximumMembers
-     */
-    if (typeof data.max_members !== 'undefined') this.maximumMembers = data.max_members || 250000;
-
-    /**
-     * The maximum amount of presences the guild can have
-     * <info>You will need to fetch the guild using {@link Guild#fetch} if you want to receive this parameter</info>
-     * @type {?number}
-     * @name Guild#maximumPresences
-     */
-    if (typeof data.max_presences !== 'undefined') this.maximumPresences = data.max_presences || 25000;
-
-    /**
-     * The approximate amount of members the guild has
-     * <info>You will need to fetch the guild using {@link Guild#fetch} if you want to receive this parameter</info>
-     * @type {?number}
-     * @name Guild#approximateMemberCount
-     */
-    if (typeof data.approximate_member_count !== 'undefined') {
-      this.approximateMemberCount = data.approximate_member_count;
+    if (typeof data.max_members !== 'undefined') {
+      /**
+       * The maximum amount of members the guild can have
+       * @type {?number}
+       */
+      this.maximumMembers = data.max_members;
+    } else if (typeof this.maximumMembers === 'undefined') {
+      this.maximumMembers = null;
+    }
+
+    if (typeof data.max_presences !== 'undefined') {
+      /**
+       * The maximum amount of presences the guild can have
+       * <info>You will need to fetch the guild using {@link Guild#fetch} if you want to receive this parameter</info>
+       * @type {?number}
+       */
+      this.maximumPresences = data.max_presences || 25000;
+    } else if (typeof this.maximumPresences === 'undefined') {
+      this.maximumPresences = null;
+    }
+
+    if (typeof data.approximate_member_count !== 'undefined') {
+      /**
+       * The approximate amount of members the guild has
+       * <info>You will need to fetch the guild using {@link Guild#fetch} if you want to receive this parameter</info>
+       * @type {?number}
+       */
+      this.approximateMemberCount = data.approximate_member_count;
+    } else if (typeof this.approximateMemberCount === 'undefined') {
+      this.approximateMemberCount = null;
     }
 
-    /**
-     * The approximate amount of presences the guild has
-     * <info>You will need to fetch the guild using {@link Guild#fetch} if you want to receive this parameter</info>
-     * @type {?number}
-     * @name Guild#approximatePresenceCount
-     */
     if (typeof data.approximate_presence_count !== 'undefined') {
+      /**
+       * The approximate amount of presences the guild has
+       * <info>You will need to fetch the guild using {@link Guild#fetch} if you want to receive this parameter</info>
+       * @type {?number}
+       */
       this.approximatePresenceCount = data.approximate_presence_count;
+    } else if (typeof this.approximatePresenceCount === 'undefined') {
+      this.approximatePresenceCount = null;
     }
 
     /**

src/structures/GuildAuditLogs.js

@@ -24,7 +24,7 @@ const Util = require('../util/Util');
 /**
  * Key mirror of all available audit log targets.
  * @name GuildAuditLogs.Targets
- * @type {AuditLogTargetType}
+ * @type {Object<string, string>}
  */
 const Targets = {
   ALL: 'ALL',
@@ -84,7 +84,7 @@ const Targets = {
 /**
  * All available actions keyed under their names to their numeric values.
  * @name GuildAuditLogs.Actions
- * @type {AuditLogAction}
+ * @type {Object<string, number>}
  */
 const Actions = {
   ALL: null,

src/structures/GuildChannel.js

@@ -17,6 +17,7 @@ const Util = require('../util/Util');
  * - {@link NewsChannel}
  * - {@link StoreChannel}
  * @extends {Channel}
+ * @abstract
  */
 class GuildChannel extends Channel {
   /**
@@ -31,6 +32,8 @@ class GuildChannel extends Channel {
      * @type {Guild}
      */
     this.guild = guild;
+
+    this.parentID = null;
   }
 
   _patch(data) {
@@ -298,7 +301,7 @@ class GuildChannel extends Channel {
    * @property {boolean} [nsfw] Whether the channel is NSFW
    * @property {number} [bitrate] The bitrate of the voice channel
    * @property {number} [userLimit] The user limit of the voice channel
-   * @property {Snowflake} [parentID] The parent ID of the channel
+   * @property {?Snowflake} [parentID] The parent ID of the channel
    * @property {boolean} [lockPermissions]
    * Lock the permissions of the channel to what the parent's permissions are
    * @property {OverwriteResolvable[]|Collection<Snowflake, OverwriteResolvable>} [permissionOverwrites]

src/structures/GuildMember.js

@@ -61,7 +61,6 @@ class GuildMember extends Base {
     /**
      * The nickname of this member, if they have one
      * @type {?string}
-     * @name GuildMember#nickname
      */
     this.nickname = null;
 
@@ -74,7 +73,6 @@ class GuildMember extends Base {
       /**
        * The user that this guild member instance represents
        * @type {User}
-       * @name GuildMember#user
        */
       this.user = this.client.users.add(data.user, true);
     }

src/structures/GuildPreview.js

@@ -75,7 +75,7 @@ class GuildPreview extends Base {
      * The description for this guild
      * @type {?string}
      */
-    this.description = data.description;
+    this.description = data.description || null;
 
     if (!this.emojis) {
       /**

src/structures/Integration.js

@@ -65,6 +65,8 @@ class Integration extends Base {
        * @type {?User}
        */
       this.user = this.client.users.add(data.user);
+    } else {
+      this.user = null;
     }
 
     /**

src/structures/MessageEmbed.js

@@ -29,37 +29,37 @@ class MessageEmbed {
      * * `link` - a link embed
      * @type {string}
      */
-    this.type = data.type;
+    this.type = data.type || 'rich';
 
     /**
      * The title of this embed
      * @type {?string}
      */
-    this.title = data.title;
+    this.title = 'title' in data ? data.title : null;
 
     /**
      * The description of this embed
      * @type {?string}
      */
-    this.description = data.description;
+    this.description = 'description' in data ? data.description : null;
 
     /**
      * The URL of this embed
      * @type {?string}
      */
-    this.url = data.url;
+    this.url = 'url' in data ? data.url : null;
 
     /**
      * The color of this embed
      * @type {?number}
      */
-    this.color = Util.resolveColor(data.color);
+    this.color = 'color' in data ? Util.resolveColor(data.color) : null;
 
     /**
      * The timestamp of this embed
      * @type {?number}
      */
-    this.timestamp = data.timestamp ? new Date(data.timestamp).getTime() : null;
+    this.timestamp = 'timestamp' in data ? new Date(data.timestamp).getTime() : null;
 
     /**
      * Represents a field of a MessageEmbed
@@ -331,7 +331,7 @@ class MessageEmbed {
    */
   setFooter(text, iconURL) {
     text = Util.resolveString(text);
-    this.footer = { text, iconURL, proxyIconURL: undefined };
+    this.footer = { text, iconURL };
     return this;
   }
 

src/structures/MessageReaction.js

@@ -46,13 +46,14 @@ class MessageReaction {
   }
 
   _patch(data) {
-    /**
-     * The number of people that have given the same reaction
-     * @type {?number}
-     * @name MessageReaction#count
-     */
     // eslint-disable-next-line eqeqeq
-    if (this.count == undefined) this.count = data.count;
+    if (this.count == undefined) {
+      /**
+       * The number of people that have given the same reaction
+       * @type {?number}
+       */
+      this.count = data.count;
+    }
   }
 
   /**

src/structures/Presence.js

@@ -184,8 +184,8 @@ class Activity {
     /**
      * Timestamps for the activity
      * @type {?Object}
-     * @prop {?Date} start When the activity started
-     * @prop {?Date} end When the activity will end
+     * @property {?Date} start When the activity started
+     * @property {?Date} end When the activity will end
      */
     this.timestamps = data.timestamps
       ? {
@@ -197,8 +197,8 @@ class Activity {
     /**
      * Party of the activity
      * @type {?Object}
-     * @prop {?string} id ID of the party
-     * @prop {number[]} size Size of the party as `[current, max]`
+     * @property {?string} id ID of the party
+     * @property {number[]} size Size of the party as `[current, max]`
      */
     this.party = data.party || null;
 

src/structures/User.js

@@ -27,6 +27,10 @@ class User extends Base {
      */
     this.id = data.id;
 
+    this.system = null;
+    this.locale = null;
+    this.flags = null;
+
     this._patch(data);
   }
 
@@ -35,7 +39,6 @@ class User extends Base {
       /**
        * The username of the user
        * @type {?string}
-       * @name User#username
        */
       this.username = data.username;
     } else if (typeof this.username !== 'string') {
@@ -45,7 +48,6 @@ class User extends Base {
     /**
      * Whether or not the user is a bot
      * @type {boolean}
-     * @name User#bot
      */
     this.bot = Boolean(data.bot);
 
@@ -53,7 +55,6 @@ class User extends Base {
       /**
        * A discriminator based on username for the user
        * @type {?string}
-       * @name User#discriminator
        */
       this.discriminator = data.discriminator;
     } else if (typeof this.discriminator !== 'string') {
@@ -64,7 +65,6 @@ class User extends Base {
       /**
        * The ID of the user's avatar
        * @type {?string}
-       * @name User#avatar
        */
       this.avatar = data.avatar;
     } else if (typeof this.avatar !== 'string') {
@@ -75,7 +75,6 @@ class User extends Base {
       /**
        * Whether the user is an Official Discord System user (part of the urgent message system)
        * @type {?boolean}
-       * @name User#system
        */
       this.system = Boolean(data.system);
     }
@@ -84,7 +83,6 @@ class User extends Base {
       /**
        * The locale of the user's client (ISO 639-1)
        * @type {?string}
-       * @name User#locale
        */
       this.locale = data.locale;
     }
@@ -93,7 +91,6 @@ class User extends Base {
       /**
        * The flags for this user
        * @type {?UserFlags}
-       * @name User#flags
        */
       this.flags = new UserFlags(data.public_flags);
     }

src/structures/VoiceChannel.js

@@ -29,7 +29,6 @@ class VoiceChannel extends GuildChannel {
   /**
    * The members in this voice channel
    * @type {Collection<Snowflake, GuildMember>}
-   * @name VoiceChannel#members
    * @readonly
    */
   get members() {

src/structures/VoiceState.js

@@ -32,32 +32,32 @@ class VoiceState extends Base {
      * Whether this member is deafened server-wide
      * @type {?boolean}
      */
-    this.serverDeaf = data.deaf;
+    this.serverDeaf = 'deaf' in data ? data.deaf : null;
     /**
      * Whether this member is muted server-wide
      * @type {?boolean}
      */
-    this.serverMute = data.mute;
+    this.serverMute = 'mute' in data ? data.mute : null;
     /**
      * Whether this member is self-deafened
      * @type {?boolean}
      */
-    this.selfDeaf = data.self_deaf;
+    this.selfDeaf = 'self_deaf' in data ? data.self_deaf : null;
     /**
      * Whether this member is self-muted
      * @type {?boolean}
      */
-    this.selfMute = data.self_mute;
+    this.selfMute = 'self_mute' in data ? data.self_mute : null;
     /**
      * Whether this member's camera is enabled
-     * @type {boolean}
+     * @type {?boolean}
      */
-    this.selfVideo = data.self_video;
+    this.selfVideo = 'self_video' in data ? data.self_video : null;
     /**
      * The session ID of this member's connection
      * @type {?string}
      */
-    this.sessionID = data.session_id;
+    this.sessionID = 'session_id' in data ? data.session_id : null;
     /**
      * Whether this member is streaming using "Go Live"
      * @type {boolean}
@@ -67,7 +67,7 @@ class VoiceState extends Base {
      * The ID of the voice channel that this member is in
      * @type {?Snowflake}
      */
-    this.channelID = data.channel_id;
+    this.channelID = data.channel_id || null;
     return this;
   }