Documentation for various controllers and libs

5 files changed, 74 insertions, 3 deletions

diff --git a/app/scripts/lib/buy-eth-url.js b/app/scripts/lib/buy-eth-url.js
index b9dde3c28..c7c7bc33c 100644
--- a/app/scripts/lib/buy-eth-url.js
+++ b/app/scripts/lib/buy-eth-url.js
@@ -1,5 +1,15 @@
 module.exports = getBuyEthUrl
 
+/**
+ * Gives the caller a url at which the user can acquire eth, depending on the network they are in
+ *
+ * @param {object} opts Options required to determine the correct url
+ * @param {string} opts.network The network for which to return a url
+ * @param {string} opts.amount The amount of ETH to buy on coinbase. Only relevant if network === '1'.
+ * @param {string} opts.address The adderss the bought ETH should be sent to.  Only relevant if network === '1'.
+ * @returns {string} The url at which the user can access ETH, while in the given network
+ *
+ */
 function getBuyEthUrl ({ network, amount, address }) {
   let url
   switch (network) {
diff --git a/app/scripts/lib/get-first-preferred-lang-code.js b/app/scripts/lib/get-first-preferred-lang-code.js
index e3635434e..78448ad43 100644
--- a/app/scripts/lib/get-first-preferred-lang-code.js
+++ b/app/scripts/lib/get-first-preferred-lang-code.js
@@ -4,6 +4,13 @@ const allLocales = require('../../_locales/index.json')
 
 const existingLocaleCodes = allLocales.map(locale => locale.code.toLowerCase().replace('_', '-'))
 
+/**
+ * Returns a preferred language code, based on settings within the user's browser. If we have no translations for the
+ * users preferred locales, 'en' is returned.
+ *
+ * @returns {string} A locale code, either one from the user's preferred list that we have a translation for, or 'en'
+ *
+ */
 async function getFirstPreferredLangCode () {
   const userPreferredLocaleCodes = await promisify(
     extension.i18n.getAcceptLanguages,
diff --git a/app/scripts/lib/is-popup-or-notification.js b/app/scripts/lib/is-popup-or-notification.js
index ad3e825c0..894564def 100644
--- a/app/scripts/lib/is-popup-or-notification.js
+++ b/app/scripts/lib/is-popup-or-notification.js
@@ -1,8 +1,14 @@
+/**
+ * Indicates whether the user is viewing the app through an extension like window or through a notification.
+ * Used to make some style decisions on the frontend, and when deciding whether to close the popup in the backend.
+ *
+ * @returns {string} Returns 'popup' if the user is viewing through the browser ('home.html') or popup extension
+ * ('popup.html'). Otherwise it returns 'notification'.
+ *
+ */
 module.exports = function isPopupOrNotification () {
   const url = window.location.href
-  // if (url.match(/popup.html$/) || url.match(/home.html$/)) {
-  // Below regexes needed for feature toggles (e.g. see line ~340 in ui/app/app.js)
-  // Revert below regexes to above commented out regexes before merge to master
+
   if (url.match(/popup.html(?:\?.+)*$/) ||
     url.match(/home.html(?:\?.+)*$/) || url.match(/home.html(?:#.*)*$/)) {
     return 'popup'
diff --git a/app/scripts/lib/nodeify.js b/app/scripts/lib/nodeify.js
index 9b595d93c..d568035c0 100644
--- a/app/scripts/lib/nodeify.js
+++ b/app/scripts/lib/nodeify.js
@@ -1,6 +1,14 @@
 const promiseToCallback = require('promise-to-callback')
 const noop = function () {}
 
+/**
+ * A generator that returns a function which, when passed a promise, can treat that promise as a node style callback.
+ * The primse advantage being that callbacks are better for error handling.
+ *
+ * @params {Function} fn The function to handle as a callback
+ * @params {Object} context The context in which the fn is to be called, most often a this reference
+ *
+ */
 module.exports = function nodeify (fn, context) {
   return function () {
     const args = [].slice.call(arguments)
diff --git a/app/scripts/lib/util.js b/app/scripts/lib/util.js
index 6dee9edf0..11565790f 100644
--- a/app/scripts/lib/util.js
+++ b/app/scripts/lib/util.js
@@ -10,11 +10,28 @@ module.exports = {
   BnMultiplyByFraction,
 }
 
+/**
+ * Generates an example stack trace
+ *
+ * @returns {string} A stack trace
+ *
+ */
 function getStack () {
   const stack = new Error('Stack trace generator - not an error').stack
   return stack
 }
 
+/**
+ * Checks whether a given balance of ETH, represented as a hex string, is sufficient to pay a value plus a gas fee
+ *
+ * @param {object} txParams Contains data about a transaction
+ * @param {string} txParams.gas The gas for a transaction
+ * @param {string} txParams.gasPrice The price per gas for the transaction
+ * @param {string} txParams.value The value of ETH to send
+ * @param {string} hexBalance A balance of ETH represented as a hex string
+ * @returns {boolean} Whether the balance is greater than or equal to the value plus the value of gas times gasPrice
+ *
+ */
 function sufficientBalance (txParams, hexBalance) {
   // validate hexBalance is a hex string
   assert.equal(typeof hexBalance, 'string', 'sufficientBalance - hexBalance is not a hex string')
@@ -29,14 +46,37 @@ function sufficientBalance (txParams, hexBalance) {
   return balance.gte(maxCost)
 }
 
+/**
+ * Converts a BN object to a hex string with a '0x' prefix
+ *
+ * @param {BN} inputBn Description
+ * @returns {string} A hex string
+ *
+ */
 function bnToHex (inputBn) {
   return ethUtil.addHexPrefix(inputBn.toString(16))
 }
 
+/**
+ * Converts a hex string to a BN object
+ *
+ * @param {string} inputHex A number represented as a hex string
+ * @returns {Object} A BN object
+ *
+ */
 function hexToBn (inputHex) {
   return new BN(ethUtil.stripHexPrefix(inputHex), 16)
 }
 
+/**
+ * Used to multiply a BN by a fraction
+ *
+ * @param {BN} targetBN The number to multiply by a fraction
+ * @param {number|string} numerator
+ * @param {number|string} denominator
+ * @returns {BN} The product of the multiplication
+ *
+ */
 function BnMultiplyByFraction (targetBN, numerator, denominator) {
   const numBN = new BN(numerator)
   const denomBN = new BN(denominator)