fix up - more docs

3 files changed, 77 insertions, 38 deletions

diff --git a/app/scripts/controllers/transactions/index.js b/app/scripts/controllers/transactions/index.js
index ca83941fc..c81251cd2 100644
--- a/app/scripts/controllers/transactions/index.js
+++ b/app/scripts/controllers/transactions/index.js
@@ -9,8 +9,6 @@ const PendingTransactionTracker = require('./pending-tx-tracker')
 const NonceTracker = require('./nonce-tracker')
 const txUtils = require('./lib/util')
 
-module.exports = TransactionController
-
 /**
   Transaction Controller is an aggregate of sub-controllers and trackers
   composing them in a way to be exposed to the metamask controller
@@ -356,6 +354,11 @@ add a new unapproved transaction to the pipeline
     })
   }
 
+  /**
+    is called in constructor applies the listeners for pendingTxTracker txStateManager
+    and blockTracker
+    <br>
+  */
   _setupListners () {
     this.txStateManager.on('tx:status-update', this.emit.bind(this, 'tx:status-update'))
     this.pendingTxTracker.on('tx:warning', (txMeta) => {
@@ -407,4 +410,6 @@ add a new unapproved transaction to the pipeline
     })
     this.memStore.updateState({ unapprovedTxs, selectedAddressTxList })
   }
-}
\ No newline at end of file
+}
+
+module.exports = TransactionController
\ No newline at end of file
diff --git a/app/scripts/controllers/transactions/lib/util.js b/app/scripts/controllers/transactions/lib/util.js
index 5d5e63c59..b18283997 100644
--- a/app/scripts/controllers/transactions/lib/util.js
+++ b/app/scripts/controllers/transactions/lib/util.js
@@ -11,24 +11,24 @@ module.exports = {
 }
 
 
+// functions that handle normalizing of that key in txParams
+const normalizers = {
+  from: from => addHexPrefix(from).toLowerCase(),
+  to: to => addHexPrefix(to).toLowerCase(),
+  nonce: nonce => addHexPrefix(nonce),
+  value: value =>  value ? addHexPrefix(value) : '0x0',
+  data: data => addHexPrefix(data),
+  gas: gas => addHexPrefix(gas),
+  gasPrice: gasPrice => addHexPrefix(gasPrice),
+}
+ /**
+ */
 function normalizeTxParams (txParams) {
-  // functions that handle normalizing of that key in txParams
-  const whiteList = {
-    from: from => addHexPrefix(from).toLowerCase(),
-    to: to => addHexPrefix(txParams.to).toLowerCase(),
-    nonce: nonce => addHexPrefix(nonce),
-    value: value => addHexPrefix(value),
-    data: data => addHexPrefix(data),
-    gas: gas => addHexPrefix(gas),
-    gasPrice: gasPrice => addHexPrefix(gasPrice),
-  }
-
-  // apply only keys in the whiteList
+  // apply only keys in the normalizers
   const normalizedTxParams = {}
-  Object.keys(whiteList).forEach((key) => {
-    if (txParams[key]) normalizedTxParams[key] = whiteList[key](txParams[key])
-  })
-
+  for (let key in normalizers) {
+    if (txParams[key]) normalizedTxParams[key] = normalizers[key](txParams[key])
+  }
   return normalizedTxParams
 }
 
diff --git a/app/scripts/controllers/transactions/pending-tx-tracker.js b/app/scripts/controllers/transactions/pending-tx-tracker.js
index f2259fb96..503343e22 100644
--- a/app/scripts/controllers/transactions/pending-tx-tracker.js
+++ b/app/scripts/controllers/transactions/pending-tx-tracker.js
@@ -1,23 +1,23 @@
 const EventEmitter = require('events')
 const EthQuery = require('ethjs-query')
-/*
-
-  Utility class for tracking the transactions as they
-  go from a pending state to a confirmed (mined in a block) state
+/**
 
+  Event emitter utility class for tracking the transactions as they<br>
+  go from a pending state to a confirmed (mined in a block) state<br>
+<br>
   As well as continues broadcast while in the pending state
+<br>
+@param config {object} - non optional configuration object consists of:
+    <br>provider
+    <br>nonceTracker: see nonce tracker
+    <br>getPendingTransactions: a function for getting an array of transactions,
+    <br>publishTransaction: a async function for publishing raw transactions,
 
-                ~config is not optional~
-  requires a: {
-    provider: //,
-    nonceTracker: //see nonce tracker,
-    getPendingTransactions: //() a function for getting an array of transactions,
-    publishTransaction: //(rawTx) a async function for publishing raw transactions,
-  }
 
+@class
 */
 
-module.exports = class PendingTransactionTracker extends EventEmitter {
+class PendingTransactionTracker extends EventEmitter {
   constructor (config) {
     super()
     this.query = new EthQuery(config.provider)
@@ -29,8 +29,13 @@ module.exports = class PendingTransactionTracker extends EventEmitter {
     this._checkPendingTxs()
   }
 
-  //  checks if a signed tx is in a block and
-  // if included sets the tx status as 'confirmed'
+  /**
+    checks if a signed tx is in a block and
+    if it is included emits tx status as 'confirmed'
+    @param block {object}, a full block
+    @emits tx:confirmed
+    @emits tx:failed
+  */
   checkForTxInBlock (block) {
     const signedTxList = this.getPendingTransactions()
     if (!signedTxList.length) return
@@ -52,6 +57,11 @@ module.exports = class PendingTransactionTracker extends EventEmitter {
     })
   }
 
+  /**
+    asks the network for the transaction to see if a block number is included on it
+    if we have skipped/missed blocks
+    @param object - oldBlock newBlock
+  */
   queryPendingTxs ({ oldBlock, newBlock }) {
     // check pending transactions on start
     if (!oldBlock) {
@@ -63,7 +73,11 @@ module.exports = class PendingTransactionTracker extends EventEmitter {
     if (diff > 1) this._checkPendingTxs()
   }
 
-
+  /**
+    Will resubmit any transactions who have not been confirmed in a block
+    @param block {object} - a block object
+    @emits tx:warning
+  */
   resubmitPendingTxs (block) {
     const pending = this.getPendingTransactions()
     // only try resubmitting if their are transactions to resubmit
@@ -100,6 +114,13 @@ module.exports = class PendingTransactionTracker extends EventEmitter {
     }))
   }
 
+  /**
+    resubmits the individual txMeta used in resubmitPendingTxs
+    @param txMeta {object} - txMeta object
+    @param latestBlockNumber {string} - hex string for the latest block number
+    @emits tx:retry
+    @returns txHash {string}
+  */
   async _resubmitTx (txMeta, latestBlockNumber) {
     if (!txMeta.firstRetryBlockNumber) {
       this.emit('tx:block-update', txMeta, latestBlockNumber)
@@ -123,7 +144,13 @@ module.exports = class PendingTransactionTracker extends EventEmitter {
     this.emit('tx:retry', txMeta)
     return txHash
   }
-
+  /**
+    Ask the network for the transaction to see if it has been include in a block
+    @param txMeta {object} - the txMeta object
+    @emits tx:failed
+    @emits tx:confirmed
+    @emits tx:warning
+  */
   async _checkPendingTx (txMeta) {
     const txHash = txMeta.hash
     const txId = txMeta.id
@@ -162,8 +189,9 @@ module.exports = class PendingTransactionTracker extends EventEmitter {
     }
   }
 
-  // checks the network for signed txs and
-  // if confirmed sets the tx status as 'confirmed'
+  /**
+    checks the network for signed txs and releases the nonce global lock if it is
+  */
   async _checkPendingTxs () {
     const signedTxList = this.getPendingTransactions()
     // in order to keep the nonceTracker accurate we block it while updating pending transactions
@@ -177,6 +205,11 @@ module.exports = class PendingTransactionTracker extends EventEmitter {
     nonceGlobalLock.releaseLock()
   }
 
+  /**
+    checks to see if a confirmed txMeta has the same nonce
+    @param txMeta {object} - txMeta object
+    @returns {boolean}
+  */
   async _checkIfNonceIsTaken (txMeta) {
     const address = txMeta.txParams.from
     const completed = this.getCompletedTransactions(address)
@@ -185,5 +218,6 @@ module.exports = class PendingTransactionTracker extends EventEmitter {
     })
     return sameNonce.length > 0
   }
-
 }
+
+module.exports = PendingTransactionTracker
\ No newline at end of file