1 files changed, 56 insertions, 0 deletions
diff --git a/app/scripts/controllers/balance.js b/app/scripts/controllers/balance.js
index f83f294cc..86619fce1 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 Stores and updates the users accounts
+   * 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 state to 'submitted', 'confirmed' or 'failed'
+   * - 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) {