doc: add jsdoc comments

lib/utils.js

@@ -1,7 +1,17 @@
 'use strict'
 
-// hgetall converts its replies to an Object. If the reply is empty, null is returned.
-// These function are only called with internal data and have therefore always the same instanceof X
+/**
+ * @description Convert an array to an object
+ *
+ * hgetall converts its replies to an object. If the reply is empty, null is returned.
+ * The reply might be a string or a buffer if this is called in a transaction (multi)
+ * because of the queuing response.
+ *
+ * reply.length can be undefined but `undefined > 0` === false.
+ *
+ * @param {any} reply
+ * @returns object
+ */
 function replyToObject (reply) {
   // The reply might be a string or a buffer if this is called in a transaction (multi)
   if (reply.length === 0 || !(reply instanceof Array)) {
@@ -14,6 +24,12 @@ function replyToObject (reply) {
   return obj
 }
 
+/**
+ * @description receive an array with values and convert all buffers to strings
+ *
+ * @param {any[]} reply
+ * @returns any[]|string
+ */
 function replyToStrings (reply) {
   if (reply === null) {
     return null
@@ -33,8 +49,15 @@ function replyToStrings (reply) {
   return reply
 }
 
-// Deep clone arbitrary objects with arrays. Can't handle cyclic structures (results in a range error)
-// Any attribute with a non primitive value besides object and array will be passed by reference (e.g. Buffers, Maps, Functions)
+/**
+ * @description Deep clone arbitrary objects with arrays.
+ * Can't handle cyclic structures (results in a range error).
+ * Any attribute with a non primitive value besides object
+ * and array will be passed by reference (e.g. Buffers, Maps, Functions)
+ *
+ * @param {any} obj
+ * @returns any
+ */
 function clone (obj) {
   var copy
   if (Array.isArray(obj)) {
@@ -55,18 +78,36 @@ function clone (obj) {
   return obj
 }
 
+/**
+ * @description Calls clone and returns an object
+ *
+ * @param {undefined|object} obj
+ * @returns object
+ */
 function convenienceClone (obj) {
   return clone(obj) || {}
 }
 
-function replyInOrder (self, callback, err, res, queue) {
-  // If the queue is explicitly passed, use that, otherwise fall back to the offline queue first,
-  // as there might be commands in both queues at the same time
+/**
+ * @description Make sure a reply is handled in order by delaying a execution
+ * the to right moment.
+ *
+ * If the queue is explicitly passed, use that, otherwise fall back to the
+ * offline queue first, as there might be commands in both queues at the same
+ * time.
+ *
+ * @param {RedisClient} client
+ * @param {function} callback
+ * @param {Error|null} err
+ * @param {any} res
+ * @param {Denque} queue
+ */
+function replyInOrder (client, callback, err, res, queue) {
   var commandObj
   if (queue) {
     commandObj = queue.peekBack()
   } else {
-    commandObj = self.offlineQueue.peekBack() || self.commandQueue.peekBack()
+    commandObj = client.offlineQueue.peekBack() || client.commandQueue.peekBack()
   }
   if (!commandObj) {
     process.nextTick(() => {