Merge pull request #4040 from MetaMask/dm-docs-2

Even more documentation for various controllers and libs.

1 files changed, 45 insertions, 8 deletions

diff --git a/app/scripts/controllers/blacklist.js b/app/scripts/controllers/blacklist.js
index d965f80b8..f100c4525 100644
--- a/app/scripts/controllers/blacklist.js
+++ b/app/scripts/controllers/blacklist.js
@@ -10,6 +10,22 @@ const POLLING_INTERVAL = 4 * 60 * 1000
 
 class BlacklistController {
 
+  /**
+   * Responsible for polling for and storing an up to date 'eth-phishing-detect' config.json file, while
+   * exposing a method that can check whether a given url is a phishing attempt. The 'eth-phishing-detect'
+   * config.json file contains a fuzzylist, whitelist and blacklist.
+   *
+   *
+   * @typedef {Object} BlacklistController
+   * @param {object} opts Overrides the defaults for the initial state of this.store
+   * @property {object} store The the store of the current phishing config
+   * @property {object} store.phishing Contains fuzzylist, whitelist and blacklist arrays. @see
+   * {@link https://github.com/MetaMask/eth-phishing-detect/blob/master/src/config.json}
+   * @property {object} _phishingDetector The PhishingDetector instantiated by passing store.phishing to
+   * PhishingDetector.
+   * @property {object} _phishingUpdateIntervalRef Id of the interval created to periodically update the blacklist
+   *
+   */
   constructor (opts = {}) {
     const initState = extend({
       phishing: PHISHING_DETECTION_CONFIG,
@@ -22,16 +38,28 @@ class BlacklistController {
     this._phishingUpdateIntervalRef = null
   }
 
-  //
-  // PUBLIC METHODS
-  //
-
+  /**
+   * Given a url, returns the result of checking if that url is in the store.phishing blacklist
+   *
+   * @param {string} hostname The hostname portion of a url; the one that will be checked against the white and
+   * blacklists of store.phishing
+   * @returns {boolean} Whether or not the passed hostname is on our phishing blacklist
+   *
+   */
   checkForPhishing (hostname) {
     if (!hostname) return false
     const { result } = this._phishingDetector.check(hostname)
     return result
   }
 
+  /**
+   * Queries `https://api.infura.io/v2/blacklist` for an updated blacklist config. This is passed to this._phishingDetector
+   * to update our phishing detector instance, and is updated in the store. The new phishing config is returned
+   *
+   *
+   * @returns {Promise<object>} Promises the updated blacklist config for the phishingDetector
+   *
+   */
   async updatePhishingList () {
     const response = await fetch('https://api.infura.io/v2/blacklist')
     const phishing = await response.json()
@@ -40,6 +68,11 @@ class BlacklistController {
     return phishing
   }
 
+  /**
+   * Initiates the updating of the local blacklist at a set interval. The update is done via this.updatePhishingList().
+   * Also, this method store a reference to that interval at this._phishingUpdateIntervalRef
+   *
+   */
   scheduleUpdates () {
     if (this._phishingUpdateIntervalRef) return
     this.updatePhishingList().catch(log.warn)
@@ -48,10 +81,14 @@ class BlacklistController {
     }, POLLING_INTERVAL)
   }
 
-  //
-  // PRIVATE METHODS
-  //
-
+  /**
+   * Sets this._phishingDetector to a new PhishingDetector instance.
+   * @see {@link https://github.com/MetaMask/eth-phishing-detect}
+   *
+   * @private
+   * @param {object} config A config object like that found at {@link https://github.com/MetaMask/eth-phishing-detect/blob/master/src/config.json}
+   * 
+   */
   _setupPhishingDetector (config) {
     this._phishingDetector = new PhishingDetector(config)
   }