Documentation for various controllers and libs

1 files changed, 74 insertions, 0 deletions

diff --git a/app/scripts/controllers/shapeshift.js b/app/scripts/controllers/shapeshift.js
index 3bbfaa1c5..b24b010ea 100644
--- a/app/scripts/controllers/shapeshift.js
+++ b/app/scripts/controllers/shapeshift.js
@@ -6,6 +6,17 @@ const POLLING_INTERVAL = 3000
 
 class ShapeshiftController {
 
+    /**
+     * Controller responsible for managing the list of shapeshift transactions. On construction, it initiates a poll
+     * that queries a shapeshift.io API for updates to any pending shapeshift transactions
+     *
+     * @typedef {Object} ShapeshiftController
+     * @param {object} opts Overides the defaults for the initial state of this.store
+     * @property {array} opts.initState  initializes the the state of the ShapeshiftController. Can contain an
+     * shapeShiftTxList array.
+     * @property {array} shapeShiftTxList An array of ShapeShiftTx objects
+     *
+     */
   constructor (opts = {}) {
     const initState = extend({
       shapeShiftTxList: [],
@@ -14,21 +25,54 @@ class ShapeshiftController {
     this.pollForUpdates()
   }
 
+  /**
+   * Represents, and contains data about, a single shapeshift transaction.
+   * @typedef {Object} ShapeShiftTx
+   * @property {string} depositAddress - An address at which to send a crypto deposit, so that eth can be sent to the
+   * user's Metamask account
+   * @property {string} depositType - An abbreviation of the type of crypto currency to be deposited.
+   * @constant {string} key - The 'shapeshift' key differentiates this from other types of txs in Metamask
+   * @property {number} time - The time at which the tx was created
+   * @property {object} response - Initiated as an empty object, which will be replaced by a Response object. @see {@link
+   * https://developer.mozilla.org/en-US/docs/Web/API/Response}
+   */
+
   //
   // PUBLIC METHODS
   //
 
+	/**
+	 * A getter for the shapeShiftTxList property
+	 *
+	 * @returns {array<ShapeShiftTx>}
+	 *
+	 */
   getShapeShiftTxList () {
     const shapeShiftTxList = this.store.getState().shapeShiftTxList
     return shapeShiftTxList
   }
 
+	/**
+	 * A getter for all ShapeShiftTx in the shapeShiftTxList that have not successfully completed a deposit.
+	 *
+	 * @returns {array<ShapeShiftTx>} Only includes ShapeShiftTx which has a response property with a status !== complete
+	 *
+	 */
   getPendingTxs () {
     const txs = this.getShapeShiftTxList()
     const pending = txs.filter(tx => tx.response && tx.response.status !== 'complete')
     return pending
   }
 
+	/**
+	 * A poll that exists as long as there are pending transactions. Each call attempts to update the data of any
+   * pendingTxs, and then calls itself again. If there are no pending txs, the recursive call is not made and
+   * the polling stops.
+   *
+   * this.updateTx is used to attempt the update to the pendingTxs in the ShapeShiftTxList, and that updated data
+   * is saved with saveTx.
+	 *
+	 */
   pollForUpdates () {
     const pendingTxs = this.getPendingTxs()
 
@@ -45,6 +89,15 @@ class ShapeshiftController {
     })
   }
 
+    /**
+     * Attempts to update a ShapeShiftTx with data from a shapeshift.io API. Both the response and time properties
+     * can be updated. The response property is updated with every call, but the time property is only updated when
+     * the response status updates to 'complete'. This will occur once the user makes a deposit as the ShapeShiftTx
+     * depositAddress
+     *
+     * @param {ShapeShiftTx} tx The tx to update
+     *
+     */
   async updateTx (tx) {
     try {
       const url = `https://shapeshift.io/txStat/${tx.depositAddress}`
@@ -60,6 +113,13 @@ class ShapeshiftController {
     }
   }
 
+	/**
+	 * Saves an updated to a ShapeShiftTx in the shapeShiftTxList. If the passed ShapeShiftTx is not in the
+   * shapeShiftTxList, nothing happens.
+	 *
+	 * @params {ShapeShiftTx} tx The updated tx to save, if it exists in the current shapeShiftTxList
+	 *
+	 */
   saveTx (tx) {
     const { shapeShiftTxList } = this.store.getState()
     const index = shapeShiftTxList.indexOf(tx)
@@ -69,6 +129,12 @@ class ShapeshiftController {
     }
   }
 
+	/**
+	 * Removes a ShapeShiftTx from the shapeShiftTxList
+	 *
+	 * @params {ShapeShiftTx} tx The tx to remove
+	 *
+	 */
   removeShapeShiftTx (tx) {
     const { shapeShiftTxList } = this.store.getState()
     const index = shapeShiftTxList.indexOf(index)
@@ -78,6 +144,14 @@ class ShapeshiftController {
     this.updateState({ shapeShiftTxList })
   }
 
+	/**
+	 * Creates a new ShapeShiftTx, adds it to the shapeShiftTxList, and initiates a new poll for updates of pending txs
+	 *
+   * @param {string} depositAddress - An address at which to send a crypto deposit, so that eth can be sent to the
+   * user's Metamask account
+   * @param {string} depositType - An abbreviation of the type of crypto currency to be deposited.
+	 *
+	 */
   createShapeShiftTx (depositAddress, depositType) {
     const state = this.store.getState()
     let { shapeShiftTxList } = state