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

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

src/client/voice/VoiceConnection.js

@@ -165,7 +165,7 @@ class VoiceConnection extends EventEmitter {
 
   /**
    * The voice state of this connection
-   * @type {VoiceState}
+   * @type {?VoiceState}
    */
   get voice() {
     return this.channel.guild.voice;
@@ -203,8 +203,8 @@ class VoiceConnection extends EventEmitter {
    * Set the token and endpoint required to connect to the voice servers.
    * @param {string} token The voice token
    * @param {string} endpoint The voice endpoint
-   * @private
    * @returns {void}
+   * @private
    */
   setTokenAndEndpoint(token, endpoint) {
     this.emit('debug', `Token "${token}" and endpoint "${endpoint}"`);

src/client/voice/dispatcher/StreamDispatcher.js

@@ -56,7 +56,7 @@ class StreamDispatcher extends Writable {
      * The broadcast controlling this dispatcher, if any
      * @type {?VoiceBroadcast}
      */
-    this.broadcast = this.streams.broadcast;
+    this.broadcast = this.streams.broadcast || null;
 
     this._pausedTime = 0;
     this._silentPausedTime = 0;

src/client/websocket/WebSocketManager.js

@@ -43,7 +43,7 @@ class WebSocketManager extends EventEmitter {
      * The gateway this manager uses
      * @type {?string}
      */
-    this.gateway = undefined;
+    this.gateway = null;
 
     /**
      * The amount of shards this manager handles
@@ -98,11 +98,11 @@ class WebSocketManager extends EventEmitter {
      * The current session limit of the client
      * @private
      * @type {?Object}
-     * @prop {number} total Total number of identifies available
-     * @prop {number} remaining Number of identifies remaining
-     * @prop {number} reset_after Number of milliseconds after which the limit resets
+     * @property {number} total Total number of identifies available
+     * @property {number} remaining Number of identifies remaining
+     * @property {number} reset_after Number of milliseconds after which the limit resets
      */
-    this.sessionStartLimit = undefined;
+    this.sessionStartLimit = null;
   }
 
   /**
@@ -212,7 +212,7 @@ class WebSocketManager extends EventEmitter {
 
         if (UNRESUMABLE_CLOSE_CODES.includes(event.code)) {
           // These event codes cannot be resumed
-          shard.sessionID = undefined;
+          shard.sessionID = null;
         }
 
         /**

src/client/websocket/WebSocketShard.js

@@ -56,10 +56,10 @@ class WebSocketShard extends EventEmitter {
 
     /**
      * The current session ID of the shard
-     * @type {string}
+     * @type {?string}
      * @private
      */
-    this.sessionID = undefined;
+    this.sessionID = null;
 
     /**
      * The previous heartbeat ping of the shard
@@ -124,7 +124,7 @@ class WebSocketShard extends EventEmitter {
      * @type {?NodeJS.Timeout}
      * @private
      */
-    Object.defineProperty(this, 'helloTimeout', { value: undefined, writable: true });
+    Object.defineProperty(this, 'helloTimeout', { value: null, writable: true });
 
     /**
      * If the manager attached its event handlers on the shard
@@ -140,15 +140,15 @@ class WebSocketShard extends EventEmitter {
      * @type {?Set<string>}
      * @private
      */
-    Object.defineProperty(this, 'expectedGuilds', { value: undefined, writable: true });
+    Object.defineProperty(this, 'expectedGuilds', { value: null, writable: true });
 
     /**
      * The ready timeout
      * @name WebSocketShard#readyTimeout
      * @type {?NodeJS.Timeout}
      * @private
      */
-    Object.defineProperty(this, 'readyTimeout', { value: undefined, writable: true });
+    Object.defineProperty(this, 'readyTimeout', { value: null, writable: true });
 
     /**
      * Time when the WebSocket connection was opened
@@ -428,7 +428,7 @@ class WebSocketShard extends EventEmitter {
         // Reset the sequence
         this.sequence = -1;
         // Reset the session ID as it's invalid
-        this.sessionID = undefined;
+        this.sessionID = null;
         // Set the status to reconnecting
         this.status = Status.RECONNECTING;
         // Finally, emit the INVALID_SESSION event
@@ -457,7 +457,7 @@ class WebSocketShard extends EventEmitter {
     // Step 0. Clear the ready timeout, if it exists
     if (this.readyTimeout) {
       this.manager.client.clearTimeout(this.readyTimeout);
-      this.readyTimeout = undefined;
+      this.readyTimeout = null;
     }
     // Step 1. If we don't have any other guilds pending, we are ready
     if (!this.expectedGuilds.size) {
@@ -480,7 +480,7 @@ class WebSocketShard extends EventEmitter {
       this.debug(`Shard did not receive any more guild packets in 15 seconds.
   Unavailable guild count: ${this.expectedGuilds.size}`);
 
-      this.readyTimeout = undefined;
+      this.readyTimeout = null;
 
       this.status = Status.READY;
 
@@ -498,7 +498,7 @@ class WebSocketShard extends EventEmitter {
       if (this.helloTimeout) {
         this.debug('Clearing the HELLO timeout.');
         this.manager.client.clearTimeout(this.helloTimeout);
-        this.helloTimeout = undefined;
+        this.helloTimeout = null;
       }
       return;
     }
@@ -519,7 +519,7 @@ class WebSocketShard extends EventEmitter {
       if (this.heartbeatInterval) {
         this.debug('Clearing the heartbeat interval.');
         this.manager.client.clearInterval(this.heartbeatInterval);
-        this.heartbeatInterval = undefined;
+        this.heartbeatInterval = null;
       }
       return;
     }
@@ -734,7 +734,7 @@ class WebSocketShard extends EventEmitter {
     // Step 5: Reset the sequence and session ID if requested
     if (reset) {
       this.sequence = -1;
-      this.sessionID = undefined;
+      this.sessionID = null;
     }
 
     // Step 6: reset the ratelimit data

src/sharding/Shard.js

@@ -44,7 +44,7 @@ class Shard extends EventEmitter {
 
     /**
      * Arguments for the shard's process executable (only when {@link ShardingManager#mode} is `process`)
-     * @type {?string[]}
+     * @type {string[]}
      */
     this.execArgv = manager.execArgv;
 
@@ -96,7 +96,7 @@ class Shard extends EventEmitter {
      * @type {Function}
      * @private
      */
-    this._exitListener = this._handleExit.bind(this, undefined);
+    this._exitListener = this._handleExit.bind(this);
   }
 
   /**

src/sharding/ShardClientUtil.js

@@ -125,7 +125,7 @@ class ShardClientUtil {
   }
 
   /**
-   * Evaluates a script or function on all shards, in the context of the {@link Clients}.
+   * Evaluates a script or function on all shards, in the context of the {@link Client}s.
    * @param {string|Function} script JavaScript to run on each shard
    * @returns {Promise<Array<*>>} Results of the script execution
    * @example

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) {