Merge pull request #3984 from whymarrh/3941-jsdoc

Add a few docblocks to background files

7 files changed, 120 insertions, 28 deletions

diff --git a/app/scripts/lib/createLoggerMiddleware.js b/app/scripts/lib/createLoggerMiddleware.js
index fc6abf828..996c3477c 100644
--- a/app/scripts/lib/createLoggerMiddleware.js
+++ b/app/scripts/lib/createLoggerMiddleware.js
@@ -1,16 +1,20 @@
 const log = require('loglevel')
 
-// log rpc activity
 module.exports = createLoggerMiddleware
 
-function createLoggerMiddleware ({ origin }) {
-  return function loggerMiddleware (req, res, next, end) {
-    next((cb) => {
+/**
+ * Returns a middleware that logs RPC activity
+ * @param {{ origin: string }} opts - The middleware options
+ * @returns {Function}
+ */
+function createLoggerMiddleware (opts) {
+  return function loggerMiddleware (/** @type {any} */ req, /** @type {any} */ res, /** @type {Function} */ next) {
+    next((/** @type {Function} */ cb) => {
       if (res.error) {
         log.error('Error in RPC response:\n', res)
       }
       if (req.isMetamaskInternal) return
-      log.info(`RPC (${origin}):`, req, '->', res)
+      log.info(`RPC (${opts.origin}):`, req, '->', res)
       cb()
     })
   }
diff --git a/app/scripts/lib/createOriginMiddleware.js b/app/scripts/lib/createOriginMiddleware.js
index f8bdb2dc2..98bb0e3b3 100644
--- a/app/scripts/lib/createOriginMiddleware.js
+++ b/app/scripts/lib/createOriginMiddleware.js
@@ -1,9 +1,13 @@
-// append dapp origin domain to request
 module.exports = createOriginMiddleware
 
-function createOriginMiddleware ({ origin }) {
-  return function originMiddleware (req, res, next, end) {
-    req.origin = origin
+/**
+ * Returns a middleware that appends the DApp origin to request
+ * @param {{ origin: string }} opts - The middleware options
+ * @returns {Function}
+ */
+function createOriginMiddleware (opts) {
+  return function originMiddleware (/** @type {any} */ req, /** @type {any} */ _, /** @type {Function} */ next) {
+    req.origin = opts.origin
     next()
   }
 }
diff --git a/app/scripts/lib/events-proxy.js b/app/scripts/lib/events-proxy.js
index c0a490b05..f83773ccc 100644
--- a/app/scripts/lib/events-proxy.js
+++ b/app/scripts/lib/events-proxy.js
@@ -1,26 +1,37 @@
+/**
+ * Returns an EventEmitter that proxies events from the given event emitter
+ * @param {any} eventEmitter
+ * @param {object} listeners - The listeners to proxy to
+ * @returns {any}
+ */
 module.exports = function createEventEmitterProxy (eventEmitter, listeners) {
   let target = eventEmitter
   const eventHandlers = listeners || {}
-  const proxy = new Proxy({}, {
-    get: (obj, name) => {
+  const proxy = /** @type {any} */ (new Proxy({}, {
+    get: (_, name) => {
       // intercept listeners
       if (name === 'on') return addListener
       if (name === 'setTarget') return setTarget
       if (name === 'proxyEventHandlers') return eventHandlers
-      return target[name]
+      return (/** @type {any} */ (target))[name]
     },
-    set: (obj, name, value) => {
+    set: (_, name, value) => {
       target[name] = value
       return true
     },
-  })
-  function setTarget (eventEmitter) {
+  }))
+  function setTarget (/** @type {EventEmitter} */ eventEmitter) {
     target = eventEmitter
     // migrate listeners
     Object.keys(eventHandlers).forEach((name) => {
-      eventHandlers[name].forEach((handler) => target.on(name, handler))
+      /** @type {Array<Function>} */ (eventHandlers[name]).forEach((handler) => target.on(name, handler))
     })
   }
+  /**
+   * Attaches a function to be called whenever the specified event is emitted
+   * @param {string} name
+   * @param {Function} handler
+   */
   function addListener (name, handler) {
     if (!eventHandlers[name]) eventHandlers[name] = []
     eventHandlers[name].push(handler)
diff --git a/app/scripts/lib/hex-to-bn.js b/app/scripts/lib/hex-to-bn.js
index 184217279..b28746920 100644
--- a/app/scripts/lib/hex-to-bn.js
+++ b/app/scripts/lib/hex-to-bn.js
@@ -1,6 +1,11 @@
-const ethUtil = require('ethereumjs-util')
+const ethUtil = (/** @type {object} */ (require('ethereumjs-util')))
 const BN = ethUtil.BN
 
+/**
+ * Returns a [BinaryNumber]{@link BN} representation of the given hex value
+ * @param {string} hex
+ * @return {any}
+ */
 module.exports = function hexToBn (hex) {
   return new BN(ethUtil.stripHexPrefix(hex), 16)
 }
diff --git a/app/scripts/lib/local-store.js b/app/scripts/lib/local-store.js
index 2dda0ba1f..139ff86bd 100644
--- a/app/scripts/lib/local-store.js
+++ b/app/scripts/lib/local-store.js
@@ -1,11 +1,13 @@
-// We should not rely on local storage in an extension!
-// We should use this instead!
-// https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/local
-
 const extension = require('extensionizer')
 const log = require('loglevel')
 
+/**
+ * A wrapper around the extension's storage local API
+ */
 module.exports = class ExtensionStore {
+  /**
+   * @constructor
+   */
   constructor() {
     this.isSupported = !!(extension.storage.local)
     if (!this.isSupported) {
@@ -13,6 +15,10 @@ module.exports = class ExtensionStore {
     }
   }
 
+  /**
+   * Returns all of the keys currently saved
+   * @return {Promise<*>}
+   */
   async get() {
     if (!this.isSupported) return undefined
     const result = await this._get()
@@ -25,14 +31,24 @@ module.exports = class ExtensionStore {
     }
   }
 
+  /**
+   * Sets the key in local state
+   * @param {object} state - The state to set
+   * @return {Promise<void>}
+   */
   async set(state) {
     return this._set(state)
   }
 
+  /**
+   * Returns all of the keys currently saved
+   * @private
+   * @return {object} the key-value map from local storage
+   */
   _get() {
     const local = extension.storage.local
     return new Promise((resolve, reject) => {
-      local.get(null, (result) => {
+      local.get(null, (/** @type {any} */ result) => {
         const err = extension.runtime.lastError
         if (err) {
           reject(err)
@@ -43,6 +59,12 @@ module.exports = class ExtensionStore {
     })
   }
 
+  /**
+   * Sets the key in local state
+   * @param {object} obj - The key to set
+   * @return {Promise<void>}
+   * @private
+   */
   _set(obj) {
     const local = extension.storage.local
     return new Promise((resolve, reject) => {
@@ -58,6 +80,11 @@ module.exports = class ExtensionStore {
   }
 }
 
+/**
+ * Returns whether or not the given object contains no keys
+ * @param {object} obj - The object to check
+ * @returns {boolean}
+ */
 function isEmpty(obj) {
   return Object.keys(obj).length === 0
 }
diff --git a/app/scripts/lib/migrator/index.js b/app/scripts/lib/migrator/index.js
index 85c2717ea..345ca8001 100644
--- a/app/scripts/lib/migrator/index.js
+++ b/app/scripts/lib/migrator/index.js
@@ -1,7 +1,23 @@
 const EventEmitter = require('events')
 
+/**
+ * @typedef {object} Migration
+ * @property {number} version - The migration version
+ * @property {Function} migrate - Returns a promise of the migrated data
+ */
+
+/**
+ * @typedef {object} MigratorOptions
+ * @property {Array<Migration>} [migrations] - The list of migrations to apply
+ * @property {number} [defaultVersion] - The version to use in the initial state
+ */
+
 class Migrator extends EventEmitter {
 
+  /**
+   * @constructor
+   * @param {MigratorOptions} opts
+   */
   constructor (opts = {}) {
     super()
     const migrations = opts.migrations || []
@@ -42,19 +58,30 @@ class Migrator extends EventEmitter {
 
     return versionedData
 
-    // migration is "pending" if it has a higher
-    // version number than currentVersion
+    /**
+     * Returns whether or not the migration is pending
+     *
+     * A migration is considered "pending" if it has a higher
+     * version number than the current version.
+     * @param {Migration} migration
+     * @returns {boolean}
+     */
     function migrationIsPending (migration) {
       return migration.version > versionedData.meta.version
     }
   }
 
-  generateInitialState (initState) {
+  /**
+   * Returns the initial state for the migrator
+   * @param {object} [data] - The data for the initial state
+   * @returns {{meta: {version: number}, data: any}}
+   */
+  generateInitialState (data) {
     return {
       meta: {
         version: this.defaultVersion,
       },
-      data: initState,
+      data,
     }
   }
 
diff --git a/app/scripts/lib/stream-utils.js b/app/scripts/lib/stream-utils.js
index 8bb0b4f3c..3dbc064b5 100644
--- a/app/scripts/lib/stream-utils.js
+++ b/app/scripts/lib/stream-utils.js
@@ -8,20 +8,34 @@ module.exports = {
   setupMultiplex: setupMultiplex,
 }
 
+/**
+ * Returns a stream transform that parses JSON strings passing through
+ * @return {stream.Transform}
+ */
 function jsonParseStream () {
-  return Through.obj(function (serialized, encoding, cb) {
+  return Through.obj(function (serialized, _, cb) {
     this.push(JSON.parse(serialized))
     cb()
   })
 }
 
+/**
+ * Returns a stream transform that calls {@code JSON.stringify}
+ * on objects passing through
+ * @return {stream.Transform} the stream transform
+ */
 function jsonStringifyStream () {
-  return Through.obj(function (obj, encoding, cb) {
+  return Through.obj(function (obj, _, cb) {
     this.push(JSON.stringify(obj))
     cb()
   })
 }
 
+/**
+ * Sets up stream multiplexing for the given stream
+ * @param {any} connectionStream - the stream to mux
+ * @return {stream.Stream} the multiplexed stream
+ */
 function setupMultiplex (connectionStream) {
   const mux = new ObjectMultiplex()
   pump(