meta - transactions - docs yo!

2 files changed, 60 insertions, 4 deletions

diff --git a/app/scripts/controllers/transactions/lib/tx-state-history-helper.js b/app/scripts/controllers/transactions/lib/tx-state-history-helper.js
index 94c7b6792..7a57e3cb5 100644
--- a/app/scripts/controllers/transactions/lib/tx-state-history-helper.js
+++ b/app/scripts/controllers/transactions/lib/tx-state-history-helper.js
@@ -1,6 +1,6 @@
 const jsonDiffer = require('fast-json-patch')
 const clone = require('clone')
-
+/** @module*/
 module.exports = {
   generateHistoryEntry,
   replayHistory,
@@ -8,7 +8,11 @@ module.exports = {
   migrateFromSnapshotsToDiffs,
 }
 
-
+/**
+  converts non-initial history entries into diffs
+  @param longHistory {array}
+  @returns {array}
+*/
 function migrateFromSnapshotsToDiffs (longHistory) {
   return (
     longHistory
@@ -20,6 +24,17 @@ function migrateFromSnapshotsToDiffs (longHistory) {
   )
 }
 
+/**
+  generates an array of history objects sense the previous state.
+  The object has the keys opp(the operation preformed),
+  path(the key and if a nested object then each key will be seperated with a `/`)
+  value
+  with the first entry having the note
+  @param previousState {object} - the previous state of the object
+  @param newState {object} - the update object
+  @param note {string} - a optional note for the state change
+  @reurns {array}
+*/
 function generateHistoryEntry (previousState, newState, note) {
   const entry = jsonDiffer.compare(previousState, newState)
   // Add a note to the first op, since it breaks if we append it to the entry
@@ -27,11 +42,19 @@ function generateHistoryEntry (previousState, newState, note) {
   return entry
 }
 
+/**
+  Recovers previous txMeta state obj
+  @return {object}
+*/
 function replayHistory (_shortHistory) {
   const shortHistory = clone(_shortHistory)
   return shortHistory.reduce((val, entry) => jsonDiffer.applyPatch(val, entry).newDocument)
 }
 
+/**
+  @param txMeta {object}
+  @returns {object} a clone object of the txMeta with out history
+*/
 function snapshotFromTxMeta (txMeta) {
   // create txMeta snapshot for history
   const snapshot = clone(txMeta)
diff --git a/app/scripts/controllers/transactions/lib/util.js b/app/scripts/controllers/transactions/lib/util.js
index b18283997..84f7592a0 100644
--- a/app/scripts/controllers/transactions/lib/util.js
+++ b/app/scripts/controllers/transactions/lib/util.js
@@ -3,11 +3,15 @@ const {
   isValidAddress,
 } = require('ethereumjs-util')
 
+/**
+@module
+*/
 module.exports = {
   normalizeTxParams,
   validateTxParams,
   validateFrom,
   validateRecipient,
+  getFinalStates,
 }
 
 
@@ -16,22 +20,30 @@ const normalizers = {
   from: from => addHexPrefix(from).toLowerCase(),
   to: to => addHexPrefix(to).toLowerCase(),
   nonce: nonce => addHexPrefix(nonce),
-  value: value =>  value ? addHexPrefix(value) : '0x0',
+  value: value => addHexPrefix(value),
   data: data => addHexPrefix(data),
   gas: gas => addHexPrefix(gas),
   gasPrice: gasPrice => addHexPrefix(gasPrice),
 }
+
  /**
+  normalizes txParams
+  @param txParams {object}
+  @returns {object} normalized txParams
  */
 function normalizeTxParams (txParams) {
   // apply only keys in the normalizers
   const normalizedTxParams = {}
-  for (let key in normalizers) {
+  for (const key in normalizers) {
     if (txParams[key]) normalizedTxParams[key] = normalizers[key](txParams[key])
   }
   return normalizedTxParams
 }
 
+ /**
+  validates txParams
+  @param txParams {object}
+ */
 function validateTxParams (txParams) {
   validateFrom(txParams)
   validateRecipient(txParams)
@@ -47,11 +59,19 @@ function validateTxParams (txParams) {
   }
 }
 
+ /**
+  validates the from field in  txParams
+  @param txParams {object}
+ */
 function validateFrom (txParams) {
   if (!(typeof txParams.from === 'string')) throw new Error(`Invalid from address ${txParams.from} not a string`)
   if (!isValidAddress(txParams.from)) throw new Error('Invalid from address')
 }
 
+ /**
+  validates the to field in  txParams
+  @param txParams {object}
+ */
 function validateRecipient (txParams) {
   if (txParams.to === '0x' || txParams.to === null) {
     if (txParams.data) {
@@ -64,3 +84,16 @@ function validateRecipient (txParams) {
   }
   return txParams
 }
+
+  /**
+    @returns an {array} of states that can be considered final
+  */
+function getFinalStates () {
+  return [
+    'rejected', // the user has responded no!
+    'confirmed', // the tx has been included in a block.
+    'failed', // the tx failed for some reason, included on tx data.
+    'dropped', // the tx nonce was already used
+  ]
+}
+