Even more documentation for various controllers and libs.

4 files changed, 171 insertions, 9 deletions

diff --git a/app/scripts/controllers/balance.js b/app/scripts/controllers/balance.js
index f83f294cc..55811185a 100644
--- a/app/scripts/controllers/balance.js
+++ b/app/scripts/controllers/balance.js
@@ -4,6 +4,24 @@ const BN = require('ethereumjs-util').BN
 
 class BalanceController {
 
+  /**
+   * Controller responsible for storing and updating an account's balance.
+   *
+   * @typedef {Object} BalanceController
+   * @param {Object} opts Initialize various properties of the class.
+   * @property {string} address A base 16 hex string. The account address which has the balance managed by this
+   * BalanceController.
+   * @property {AccountTracker} accountTracker Contains and updates the users accounts; is the source of the account
+   * for which this BalanceController manages balance.
+   * @property {TransactionController} txController Stores, tracks and manages transactions. Here used to create a listener for
+   * transaction updates.
+   * @property {BlockTracker} blockTracker Tracks updates to blocks. On new blocks, this BalanceController updates its balance
+   * @property {Object} store The store for the ethBalance
+   * @property {string} store.ethBalance A base 16 hex string. The balance for the current account.
+   * @property {PendingBalanceCalculator} balanceCalc Used to calculate the accounts balance with possible pending
+   * transaction costs taken into account.
+   *
+   */
   constructor (opts = {}) {
     this._validateParams(opts)
     const { address, accountTracker, txController, blockTracker } = opts
@@ -26,6 +44,11 @@ class BalanceController {
     this._registerUpdates()
   }
 
+  /**
+   * Updates the ethBalance property to the current pending balance
+   *
+   * @returns {Promise<void>} Promises undefined
+   */
   async updateBalance () {
     const balance = await this.balanceCalc.getBalance()
     this.store.updateState({
@@ -33,6 +56,15 @@ class BalanceController {
     })
   }
 
+  /**
+   * Sets up listeners and subscriptions which should trigger an update of ethBalance. These updates include:
+   * - when a transaction changes to a submitted, confirmed or failed state
+   * - when the current account changes (i.e. a new account is selected)
+   * - when there is a block update 
+   *
+   * @private
+   *
+   */
   _registerUpdates () {
     const update = this.updateBalance.bind(this)
 
@@ -51,6 +83,14 @@ class BalanceController {
     this.blockTracker.on('block', update)
   }
 
+  /**
+   * Gets the balance, as a base 16 hex string, of the account at this BalanceController's current address.
+   * If the current account has no balance, returns undefined.
+   *
+   * @returns {Promise<BN|void>} Promises a BN with a value equal to the balance of the current account, or undefined
+   * if the current account has no balance
+   *
+   */
   async _getBalance () {
     const { accounts } = this.accountTracker.store.getState()
     const entry = accounts[this.address]
@@ -58,6 +98,14 @@ class BalanceController {
     return balance ? new BN(balance.substring(2), 16) : undefined
   }
 
+  /**
+   * Gets the pending transactions (i.e. those with a 'submitted' status). These are accessed from the
+   * TransactionController passed to this BalanceController during construction. 
+   *
+   * @private
+   * @returns {Promise<array>} Promises an array of transaction objects.
+   *
+   */
   async _getPendingTransactions () {
     const pending = this.txController.getFilteredTxList({
       from: this.address,
@@ -67,6 +115,14 @@ class BalanceController {
     return pending
   }
 
+  /**
+   * Validates that the passed options have all required properties.
+   *
+   * @param {Object} opts The options object to validate
+   * @throws {string} Throw a custom error indicating that address, accountTracker, txController and blockTracker are
+   * missing and at least one is required
+   *
+   */
   _validateParams (opts) {
     const { address, accountTracker, txController, blockTracker } = opts
     if (!address || !accountTracker || !txController || !blockTracker) {
diff --git a/app/scripts/controllers/blacklist.js b/app/scripts/controllers/blacklist.js
index df41c90c0..f100c4525 100644
--- a/app/scripts/controllers/blacklist.js
+++ b/app/scripts/controllers/blacklist.js
@@ -1,6 +1,7 @@
 const ObservableStore = require('obs-store')
 const extend = require('xtend')
 const PhishingDetector = require('eth-phishing-detect/src/detector')
+const log = require('loglevel')
 
 // compute phishing lists
 const PHISHING_DETECTION_CONFIG = require('eth-phishing-detect/src/config.json')
@@ -9,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,
@@ -21,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()
@@ -39,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)
@@ -47,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)
   }
diff --git a/app/scripts/controllers/preferences.js b/app/scripts/controllers/preferences.js
index 653e6d762..d54efb889 100644
--- a/app/scripts/controllers/preferences.js
+++ b/app/scripts/controllers/preferences.js
@@ -8,7 +8,7 @@ class PreferencesController {
 	 *
    * @typedef {Object} PreferencesController
 	 * @param {object} opts Overrides the defaults for the initial state of this.store
-   * @property {object} store The an object containing a users preferences, stored in local storage
+   * @property {object} store The stored object containing a users preferences, stored in local storage
 	 * @property {array} store.frequentRpcList A list of custom rpcs to provide the user
    * @property {string} store.currentAccountTab Indicates the selected tab in the ui
    * @property {array} store.tokens The tokens the user wants display in their token lists
diff --git a/app/scripts/controllers/recent-blocks.js b/app/scripts/controllers/recent-blocks.js
index 4ae3810eb..ddcaa7220 100644
--- a/app/scripts/controllers/recent-blocks.js
+++ b/app/scripts/controllers/recent-blocks.js
@@ -5,6 +5,23 @@ const EthQuery = require('eth-query')
 
 class RecentBlocksController {
 
+  /**
+   * Controller responsible for storing, updating and managing the recent history of blocks. Blocks are back filled
+   * upon the controller's construction and then the list is updated when the given block tracker gets a 'block' event
+   * (indicating that there is a new block to process).
+   *
+   * @typedef {Object} RecentBlocksController
+   * @param {object} opts Contains objects necessary for tracking blocks and querying the blockchain
+   * @param {BlockTracker} opts.blockTracker Contains objects necessary for tracking blocks and querying the blockchain
+   * @param {BlockTracker} opts.provider The provider used to create a new EthQuery instance.
+   * @property {BlockTracker} blockTracker Points to the passed BlockTracker. On RecentBlocksController construction,
+   * listens for 'block' events so that new blocks can be processed and added to storage.
+   * @property {EthQuery} ethQuery Points to the EthQuery instance created with the passed provider
+   * @property {number} historyLength The maximum length of blocks to track
+   * @property {object} store Stores the recentBlocks
+   * @property {array} store.recentBlocks Contains all recent blocks, up to a total that is equal to this.historyLength
+   *
+   */
   constructor (opts = {}) {
     const { blockTracker, provider } = opts
     this.blockTracker = blockTracker
@@ -20,12 +37,23 @@ class RecentBlocksController {
     this.backfill()
   }
 
+  /**
+   * Sets store.recentBlocks to an empty array
+   *
+   */
   resetState () {
     this.store.updateState({
       recentBlocks: [],
     })
   }
 
+  /**
+   * Receives a new block and modifies it with this.mapTransactionsToPrices. Then adds that block to the recentBlocks
+   * array in storage. If the recentBlocks array contains the maximum number of blocks, the oldest block is removed.
+   *
+   * @param {object} newBlock The new block to modify and add to the recentBlocks array
+   *
+   */
   processBlock (newBlock) {
     const block = this.mapTransactionsToPrices(newBlock)
 
@@ -39,6 +67,15 @@ class RecentBlocksController {
     this.store.updateState(state)
   }
 
+  /**
+   * Receives a new block and modifies it with this.mapTransactionsToPrices. Adds that block to the recentBlocks
+   * array in storage, but only if the recentBlocks array contains fewer than the maximum permitted.
+   *
+   * Unlike this.processBlock, backfillBlock adds the modified new block to the beginning of the recent block array.
+   *
+   * @param {object} newBlock The new block to modify and add to the beginning of the recentBlocks array
+   *
+   */
   backfillBlock (newBlock) {
     const block = this.mapTransactionsToPrices(newBlock)
 
@@ -51,6 +88,14 @@ class RecentBlocksController {
     this.store.updateState(state)
   }
 
+  /**
+   * Receives a block and gets the gasPrice of each of its transactions. These gas prices are added to the block at a
+   * new property, and the block's transactions are removed.
+   *
+   * @param {object} newBlock The block to modify. It's transaction array will be replaced by a gasPrices array.
+   * @returns {object} The modified block.
+   *
+   */
   mapTransactionsToPrices (newBlock) {
     const block = extend(newBlock, {
       gasPrices: newBlock.transactions.map((tx) => {
@@ -61,6 +106,16 @@ class RecentBlocksController {
     return block
   }
 
+  /**
+   * On this.blockTracker's first 'block' event after this RecentBlocksController's instantiation, the store.recentBlocks
+   * array is populated with this.historyLength number of blocks. The block number of the this.blockTracker's first
+   * 'block' event is used to iteratively generate all the numbers of the previous blocks, which are obtained by querying
+   * the blockchain. These blocks are backfilled so that the recentBlocks array is ordered from oldest to newest.
+   *
+   * Each iteration over the block numbers is delayed by 100 milliseconds.
+   *
+   * @returns {Promise<void>} Promises undefined
+   */
   async backfill() {
     this.blockTracker.once('block', async (block) => {
       let blockNum = block.number
@@ -89,12 +144,25 @@ class RecentBlocksController {
     })
   }
 
+  /**
+   * A helper for this.backfill. Provides an easy way to ensure a 100 millisecond delay using await
+   *
+   * @returns {Promise<void>} Promises undefined
+   *
+   */
   async wait () {
     return new Promise((resolve) => {
       setTimeout(resolve, 100)
     })
   }
 
+  /**
+   * Uses EthQuery to get a block that has a given block number.
+   *
+   * @param {number} number The number of the block to get
+   * @returns {Promise<object>} Promises A block with the passed number
+   *
+   */
   async getBlockByNumber (number) {
     const bn = new BN(number)
     return new Promise((resolve, reject) => {