Update tx utils JSDoc comments (#8372)

Co-authored-by: Jenny Pollack <jennypollack3@gmail.com>
Co-authored-by: Mark Stacey <markjstacey@gmail.com>

app/scripts/controllers/transactions/lib/util.js

@@ -1,10 +1,8 @@
 import { addHexPrefix, isValidAddress } from 'ethereumjs-util'
 
-
-// functions that handle normalizing of that key in txParams
 const normalizers = {
-  from: (from, LowerCase = true) => (LowerCase ? addHexPrefix(from).toLowerCase() : addHexPrefix(from)),
+  from: (from, lowerCase = true) => (lowerCase ? addHexPrefix(from).toLowerCase() : addHexPrefix(from)),
-  to: (to, LowerCase = true) => (LowerCase ? addHexPrefix(to).toLowerCase() : addHexPrefix(to)),
+  to: (to, lowerCase = true) => (lowerCase ? addHexPrefix(to).toLowerCase() : addHexPrefix(to)),
   nonce: (nonce) => addHexPrefix(nonce),
   value: (value) => addHexPrefix(value),
   data: (data) => addHexPrefix(data),
@@ -13,24 +11,26 @@ const normalizers = {
 }
 
 /**
-  normalizes txParams
+ * Normalizes the given txParams
-  @param {Object} txParams
+ * @param {Object} txParams - the tx params
-  @returns {Object} - normalized txParams
+ * @param {boolean} lowerCase - whether to return the addresses lower cased
+ * @returns {Object} the normalized tx params
  */
-export function normalizeTxParams (txParams, LowerCase) {
+export function normalizeTxParams (txParams, lowerCase) {
   // apply only keys in the normalizers
   const normalizedTxParams = {}
   for (const key in normalizers) {
     if (txParams[key]) {
-      normalizedTxParams[key] = normalizers[key](txParams[key], LowerCase)
+      normalizedTxParams[key] = normalizers[key](txParams[key], lowerCase)
     }
   }
   return normalizedTxParams
 }
 
 /**
-  validates txParams
+ * Validates the given tx parameters
-  @param {Object} txParams
+ * @param {Object} txParams - the tx params
+ * @throws {Error} if the tx params contains invalid fields
  */
 export function validateTxParams (txParams) {
   validateFrom(txParams)
@@ -48,8 +48,9 @@ export function validateTxParams (txParams) {
 }
 
 /**
-  validates the from field in  txParams
+ * Validates the {@code from} field in the given tx params
-  @param {Object} txParams
+ * @param {Object} txParams
+ * @throws {Error} if the from address isn't valid
  */
 export function validateFrom (txParams) {
   if (!(typeof txParams.from === 'string')) {
@@ -61,8 +62,10 @@ export function validateFrom (txParams) {
 }
 
 /**
-  validates the to field in  txParams
+ * Validates the {@code to} field in the given tx params
-  @param {Object} txParams
+ * @param {Object} txParams - the tx params
+ * @returns {Object} the tx params
+ * @throws {Error} if the recipient is invalid OR there isn't tx data
  */
 export function validateRecipient (txParams) {
   if (txParams.to === '0x' || txParams.to === null) {
@@ -78,8 +81,9 @@ export function validateRecipient (txParams) {
 }
 
 /**
-    @returns {array} - states that can be considered final
+ * Returns a list of final states
-  */
+ * @returns {string[]} the states that can be considered final states
+ */
 export function getFinalStates () {
   return [
     'rejected', // the user has responded no!
@@ -88,4 +92,3 @@ export function getFinalStates () {
     'dropped', // the tx nonce was already used
   ]
 }
-