[minor] Add missing JSDoc comments

Author: lpinca

lib/Extensions.js

@@ -1,31 +1,28 @@
 'use strict';
 
 /**
- * Module exports.
+ * Parse the `Sec-WebSocket-Extensions` header into an object.
+ *
+ * @param {String} value field value of the header
+ * @return {Object} The parsed object
+ * @public
  */
-
-exports.parse = parse;
-exports.format = format;
-
-/**
- * Parse extensions header value
- */
-
-function parse (value) {
+const parse = (value) => {
   value = value || '';
 
-  var extensions = {};
+  const extensions = {};
 
-  value.split(',').forEach(function (v) {
-    var params = v.split(';');
-    var token = params.shift().trim();
-    var paramsList = extensions[token] = extensions[token] || [];
-    var parsedParams = {};
+  value.split(',').forEach((v) => {
+    const params = v.split(';');
+    const token = params.shift().trim();
+    const paramsList = extensions[token] = extensions[token] || [];
+    const parsedParams = {};
 
-    params.forEach(function (param) {
-      var parts = param.trim().split('=');
-      var key = parts[0];
+    params.forEach((param) => {
+      const parts = param.trim().split('=');
+      const key = parts[0];
       var value = parts[1];
+
       if (value === undefined) {
         value = true;
       } else {
@@ -44,26 +41,27 @@ function parse (value) {
   });
 
   return extensions;
-}
+};
 
 /**
- * Format extensions header value
+ * Serialize a parsed `Sec-WebSocket-Extensions` header to a string.
+ *
+ * @param {Object} value The object to format
+ * @return {String} A string representing the given value
+ * @public
  */
-
-function format (value) {
-  return Object.keys(value).map(function (token) {
+const format = (value) => {
+  return Object.keys(value).map((token) => {
     var paramsList = value[token];
-    if (!Array.isArray(paramsList)) {
-      paramsList = [paramsList];
-    }
-    return paramsList.map(function (params) {
-      return [token].concat(Object.keys(params).map(function (k) {
+    if (!Array.isArray(paramsList)) paramsList = [paramsList];
+    return paramsList.map((params) => {
+      return [token].concat(Object.keys(params).map((k) => {
         var p = params[k];
         if (!Array.isArray(p)) p = [p];
-        return p.map(function (v) {
-          return v === true ? k : k + '=' + v;
-        }).join('; ');
+        return p.map((v) => v === true ? k : `${k}=${v}`).join('; ');
       })).join('; ');
     }).join(', ');
   }).join(', ');
-}
+};
+
+module.exports = { format, parse };

lib/PerMessageDeflate.js

@@ -29,12 +29,14 @@ class PerMessageDeflate {
   }
 
   /**
-   * Create extension parameters offer
+   * Create extension parameters offer.
    *
+   * @return {Object} Extension parameters
    * @public
    */
   offer () {
-    var params = {};
+    const params = {};
+
     if (this._options.serverNoContextTakeover) {
       params.server_no_context_takeover = true;
     }
@@ -49,12 +51,15 @@ class PerMessageDeflate {
     } else if (this._options.clientMaxWindowBits == null) {
       params.client_max_window_bits = true;
     }
+
     return params;
   }
 
   /**
-   * Accept extension offer
+   * Accept extension offer.
    *
+   * @param {Array} paramsList Extension parameters
+   * @return {Object} Accepted configuration
    * @public
    */
   accept (paramsList) {
@@ -72,7 +77,7 @@ class PerMessageDeflate {
   }
 
   /**
-   * Releases all resources used by the extension
+   * Releases all resources used by the extension.
    *
    * @public
    */
@@ -96,36 +101,45 @@ class PerMessageDeflate {
   }
 
   /**
-   * Accept extension offer from client
+   * Accept extension offer from client.
    *
+   * @param {Array} paramsList Extension parameters
+   * @return {Object} Accepted configuration
    * @private
    */
   acceptAsServer (paramsList) {
-    var accepted = {};
-    var result = paramsList.some((params) => {
-      accepted = {};
-      if (this._options.serverNoContextTakeover === false && params.server_no_context_takeover) {
-        return;
-      }
-      if (this._options.serverMaxWindowBits === false && params.server_max_window_bits) {
-        return;
-      }
-      if (typeof this._options.serverMaxWindowBits === 'number' &&
-          typeof params.server_max_window_bits === 'number' &&
-          this._options.serverMaxWindowBits > params.server_max_window_bits) {
-        return;
-      }
-      if (typeof this._options.clientMaxWindowBits === 'number' && !params.client_max_window_bits) {
+    const accepted = {};
+    const result = paramsList.some((params) => {
+      if ((
+        this._options.serverNoContextTakeover === false &&
+        params.server_no_context_takeover
+      ) || (
+        this._options.serverMaxWindowBits === false &&
+        params.server_max_window_bits
+      ) || (
+        typeof this._options.serverMaxWindowBits === 'number' &&
+        typeof params.server_max_window_bits === 'number' &&
+        this._options.serverMaxWindowBits > params.server_max_window_bits
+      ) || (
+        typeof this._options.clientMaxWindowBits === 'number' &&
+        !params.client_max_window_bits
+      )) {
         return;
       }
 
-      if (this._options.serverNoContextTakeover || params.server_no_context_takeover) {
+      if (
+        this._options.serverNoContextTakeover ||
+        params.server_no_context_takeover
+      ) {
         accepted.server_no_context_takeover = true;
       }
       if (this._options.clientNoContextTakeover) {
         accepted.client_no_context_takeover = true;
       }
-      if (this._options.clientNoContextTakeover !== false && params.client_no_context_takeover) {
+      if (
+        this._options.clientNoContextTakeover !== false &&
+        params.client_no_context_takeover
+      ) {
         accepted.client_no_context_takeover = true;
       }
       if (typeof this._options.serverMaxWindowBits === 'number') {
@@ -135,54 +149,70 @@ class PerMessageDeflate {
       }
       if (typeof this._options.clientMaxWindowBits === 'number') {
         accepted.client_max_window_bits = this._options.clientMaxWindowBits;
-      } else if (this._options.clientMaxWindowBits !== false && typeof params.client_max_window_bits === 'number') {
+      } else if (
+        this._options.clientMaxWindowBits !== false &&
+        typeof params.client_max_window_bits === 'number'
+      ) {
         accepted.client_max_window_bits = params.client_max_window_bits;
       }
       return true;
     });
 
-    if (!result) {
-      throw new Error(`Doesn't support the offered configuration`);
-    }
+    if (!result) throw new Error(`Doesn't support the offered configuration`);
 
     return accepted;
   }
 
   /**
-   * Accept extension response from server
+   * Accept extension response from server.
    *
+   * @param {Array} paramsList Extension parameters
+   * @return {Object} Accepted configuration
    * @private
    */
   acceptAsClient (paramsList) {
-    var params = paramsList[0];
+    const params = paramsList[0];
+
     if (this._options.clientNoContextTakeover != null) {
-      if (this._options.clientNoContextTakeover === false && params.client_no_context_takeover) {
+      if (
+        this._options.clientNoContextTakeover === false &&
+        params.client_no_context_takeover
+      ) {
         throw new Error('Invalid value for "client_no_context_takeover"');
       }
     }
     if (this._options.clientMaxWindowBits != null) {
-      if (this._options.clientMaxWindowBits === false && params.client_max_window_bits) {
+      if (
+        this._options.clientMaxWindowBits === false &&
+        params.client_max_window_bits
+      ) {
         throw new Error('Invalid value for "client_max_window_bits"');
       }
-      if (typeof this._options.clientMaxWindowBits === 'number' &&
-          (!params.client_max_window_bits || params.client_max_window_bits > this._options.clientMaxWindowBits)) {
+      if (
+        typeof this._options.clientMaxWindowBits === 'number' && (
+        !params.client_max_window_bits ||
+        params.client_max_window_bits > this._options.clientMaxWindowBits
+      )) {
         throw new Error('Invalid value for "client_max_window_bits"');
       }
     }
+
     return params;
   }
 
   /**
-   * Normalize extensions parameters
+   * Normalize extensions parameters.
    *
+   * @param {Array} paramsList Extension parameters
+   * @return {Array} Normalized extensions parameters
    * @private
    */
   normalizeParams (paramsList) {
     return paramsList.map((params) => {
       Object.keys(params).forEach((key) => {
         var value = params[key];
         if (value.length > 1) {
-          throw new Error('Multiple extension parameters for ' + key);
+          throw new Error(`Multiple extension parameters for ${key}`);
         }
 
         value = value[0];
@@ -283,8 +313,11 @@ class PerMessageDeflate {
   }
 
   /**
-   * Compress message
+   * Compress data.
    *
+   * @param {Buffer} data Data to compress
+   * @param {Boolean} fin Specifies whether or not this is the last fragment
+   * @param {Function} callback Callback
    * @public
    */
   compress (data, fin, callback) {

lib/WebSocket.js

@@ -375,7 +375,7 @@ class WebSocket extends EventEmitter {
   }
 
   /**
-   * Half-close the socket sending a FIN packet.
+   * Forcibly close the connection.
    *
    * @public
    */