Cleaned up some typos and JSDocs in Transactions

Nonce tracker is not fully documented yet.
Have not yet touched:
- tx-state-manager
- tx-state-history-helper
- util
- tx-gas-utils
- pending-tx-tracker

app/scripts/controllers/transactions/README.md

@@ -1,7 +1,7 @@
 # Transaction Controller
 
 Transaction Controller is an aggregate of sub-controllers and trackers
-composing them in a way to be exposed to the metamask controller
+exposed to the MetaMask controller.
 
 - txStateManager
     responsible for the state of a transaction and
@@ -14,11 +14,11 @@ composing them in a way to be exposed to the metamask controller
 - nonceTracker
     calculating nonces
 
-## flow digram of processing a transaction
+## Flow diagram of processing a transaction
 
 ![transaction-flow](../../../../docs/transaction-flow.png)
 
-## txMeta's && txParams
+## txMeta's & txParams
 
 A txMeta is the "meta" object it has all the random bits of info we need about a transaction on it. txParams are sacred every thing on txParams gets signed so it must
 be a valid key and be hex prefixed except for the network number. Extra stuff must go on the txMeta!
@@ -59,8 +59,8 @@ txMeta = {
               "value": "0x3b9aca00"
             },
             ...], // I've removed most of history for this
-  "gasPriceSpecified": false, //weather or not the user/dapp has specified gasPrice
+  "gasPriceSpecified": false, //whether or not the user/dapp has specified gasPrice
-  "gasLimitSpecified": false, //weather or not the user/dapp has specified gas
+  "gasLimitSpecified": false, //whether or not the user/dapp has specified gas
   "estimatedGas": "5208",
   "origin": "MetaMask", //debug
   "nonceDetails": {

app/scripts/controllers/transactions/index.js

@@ -25,17 +25,18 @@ const log = require('loglevel')
       calculating nonces
 
 
-@param {object} opts -
+  @class
-  @property  {object} opts.initState initial transaction list default is an empty array
+  @param {Object} opts
+  @property  {Object} opts.initState initial transaction list default is an empty array
   @property  {Object} opts.networkStore an observable store for network number
-  @property  {Object} opts.blockTracker
+  @param {Object} opts.blockTracker - An instance of eth-blocktracker
   @property  {Object} opts.provider
+  @param {Object} opts.provider - A network provider.
   @property  {Object} opts.signTransaction function the signs an ethereumjs-tx
   @property  {function} opts.getGasPrice optional gas price calculator
   @property  {function} opts.signTransaction ethTx signer that returns a rawTx
   @property  {number} opts.txHistoryLimit number *optional* for limiting how many transactions are in state
   @property  {Object} opts.preferencesStore
-@class
 */
 
 class TransactionController extends EventEmitter {
@@ -105,7 +106,7 @@ class TransactionController extends EventEmitter {
 
   /**
   wipes the transactions for a given account
-  @param address {string} - hex string of the from address for txs being removed
+  @param {string} address - hex string of the from address for txs being removed
   */
   wipeTransactions (address) {
     this.txStateManager.wipeTransactions(address)
@@ -113,10 +114,10 @@ class TransactionController extends EventEmitter {
 
   /**
   add a new unapproved transaction to the pipeline
-@returns {promise}
-@param txParams {object} - txParams for the transaction
-@param opts {object} - with the key origin to put the origin on the txMeta
 
+  @returns {promise}
+  @param txParams {Object} - txParams for the transaction
+  @param opts {Object} - with the key origin to put the origin on the txMeta
   */
   async newUnapprovedTransaction (txParams, opts = {}) {
     log.debug(`MetaMaskController newUnapprovedTransaction ${JSON.stringify(txParams)}`)
@@ -171,7 +172,7 @@ add a new unapproved transaction to the pipeline
   }
 /**
   adds the tx gas defaults: gas && gasPrice
-  @param txMeta {object} - the txMeta object
+  @param txMeta {Object} - the txMeta object
   @returns {promise} resolves with txMeta
 */
   async addTxGasDefaults (txMeta) {
@@ -211,7 +212,7 @@ add a new unapproved transaction to the pipeline
 
   /**
   updates the txMeta in the txStateManager
-  @param txMeta {object} - the updated txMeta
+  @param txMeta {Object} - the updated txMeta
   */
   async updateTransaction (txMeta) {
     this.txStateManager.updateTx(txMeta, 'confTx: user updated transaction')
@@ -219,7 +220,7 @@ add a new unapproved transaction to the pipeline
 
   /**
   updates and approves the transaction
-  @param txMeta {object}
+  @param txMeta {Object}
   */
   async updateAndApproveTransaction (txMeta) {
     this.txStateManager.updateTx(txMeta, 'confTx: user approved transaction')

app/scripts/controllers/transactions/nonce-tracker.js

@@ -2,12 +2,12 @@ const EthQuery = require('ethjs-query')
 const assert = require('assert')
 const Mutex = require('await-semaphore').Mutex
 /**
-  @param opts {object} -
+  @param opts {Object} -
     @property {Object} opts.provider a ethereum provider
-    @property {function} opts.getPendingTransactions a function that returns an array of txMeta
+    @property {Function} opts.getPendingTransactions a function that returns an array of txMeta
-    whos status is `submitted`
+    whosee status is `submitted`
-    @property {function} opts.getConfirmedTransactions a function that returns an array of txMeta
+    @property {Function} opts.getConfirmedTransactions a function that returns an array of txMeta
-    whos status is `confirmed`
+    whose status is `confirmed`
   @class
 */
 class NonceTracker {
@@ -21,7 +21,7 @@ class NonceTracker {
   }
 
   /**
-    @returns {object} with the key releaseLock (the gloabl mutex)
+    @returns {Promise<Object>} with the key releaseLock (the gloabl mutex)
   */
   async getGlobalLock () {
     const globalMutex = this._lookupMutex('global')
@@ -31,17 +31,18 @@ class NonceTracker {
   }
 
   /**
-  this will return an object with the `nextNonce` `nonceDetails` which is an
+   * @typedef NonceDetails
-  object with:
+   * @property {number} highestLocallyConfirmed - A hex string of the highest nonce on a confirmed transaction.
-      highestLocallyConfirmed (nonce),
+   * @property {number} nextNetworkNonce - The next nonce suggested by the eth_getTransactionCount method.
-      highestSuggested (either the network nonce or the highestLocallyConfirmed nonce),
+   * @property {number} highetSuggested - The maximum between the other two, the number returned.
-      nextNetworkNonce (the nonce suggested by the network),
+   */
-  and the releaseLock
-  <br>note: releaseLock must be called after adding signed tx to pending transactions
-  (or discarding)<br>
 
-  @param address {string} the hex string for the address whos nonce we are calculating
+  /**
-  @returns {object}
+  this will return an object with the `nextNonce` `nonceDetails` of type NonceDetails, and the releaseLock
+  Note: releaseLock must be called after adding a signed tx to pending transactions (or discarding).
+
+  @param address {string} the hex string for the address whose nonce we are calculating
+  @returns {Promise<Object>}
   */
   async getNonceLock (address) {
     // await global mutex free