adding some additional documentation

contracts/mainnet/connectors/notional/helpers.sol

@@ -14,38 +14,44 @@ contract Helpers is Basic {
     uint8 internal constant BORROW_TRADE = 1;
     int256 internal constant INTERNAL_TOKEN_PRECISION = 1e8;
     uint256 internal constant ETH_CURRENCY_ID = 1;
+    uint256 internal constant MAX_DEPOSIT = uint256(-1);
 
+    /// @dev Contract address is different on Kovan: 0x0EAE7BAdEF8f95De91fDDb74a89A786cF891Eb0e
     NotionalInterface internal constant notional =
         NotionalInterface(0x1344A36A1B56144C3Bc62E7757377D288fDE0369);
 
+    /// @notice Returns the address of the underlying token for a given currency id, 
     function getUnderlyingToken(uint16 currencyId) internal returns (address) {
-        (, Token memory underlyingToken) = notional.getCurrency(currencyId);
+        (
+            /* Token memory assetToken */,
+            Token memory underlyingToken
+        ) = notional.getCurrency(currencyId);
         return underlyingToken.tokenAddress;
     }
 
+    /// @notice Returns the address of the asset token for a given currency id
     function getAssetToken(uint16 currencyId) internal returns (address) {
-        (Token memory assetToken, ) = notional.getCurrency(currencyId);
+        (
+            Token memory assetToken,
+            /* Token memory underlyingToken */
+        ) = notional.getCurrency(currencyId);
         return assetToken.tokenAddress;
     }
 
-    function getCashBalance(uint16 currencyId)
+    function getCashBalance(uint16 currencyId) internal returns (int256 cashBalance) {
-        internal
+        (
-        returns (int256 cashBalance)
+            cashBalance,
-    {
+            /* int256 nTokenBalance */,
-        (cashBalance, , ) = notional.getAccountBalance(
+            /* int256 lastClaimTime */
-            currencyId,
+        ) = notional.getAccountBalance(currencyId, address(this));
-            address(this)
-        );
     }
 
-    function getNTokenBalance(uint16 currencyId)
+    function getNTokenBalance(uint16 currencyId) internal returns (int256 nTokenBalance) {
-        internal
+        (
-        returns (int256 nTokenBalance)
+            /* int256 cashBalance */,
-    {
+            nTokenBalance,
-        (, nTokenBalance, ) = notional.getAccountBalance(
+            /* int256 lastClaimTime */
-            currencyId,
+        ) = notional.getAccountBalance(currencyId, address(this));
-            address(this)
-        );
     }
 
     function convertToInternal(uint16 currencyId, int256 amount)
@@ -56,7 +62,7 @@ contract Helpers is Basic {
         // down to the internal precision. Resulting dust will accumulate to the protocol.
         // If token decimals is less than INTERNAL_TOKEN_PRECISION then this will add zeros to the
         // end of amount and will not result in dust.
-        (Token memory assetToken, ) = notional.getCurrency(currencyId);
+        (Token memory assetToken, /* underlyingToken */) = notional.getCurrency(currencyId);
         if (assetToken.decimals == INTERNAL_TOKEN_PRECISION) return amount;
         return amount.mul(INTERNAL_TOKEN_PRECISION).div(assetToken.decimals);
     }
@@ -85,6 +91,8 @@ contract Helpers is Basic {
             (bytes32(uint256(maxBorrowRate)) << 120);
     }
 
+    /// @dev Uses getId to set approval for the given token up to the specified deposit
+    /// amount only
     function getDepositAmountAndSetApproval(
         uint256 getId,
         uint16 currencyId,
@@ -92,16 +100,18 @@ contract Helpers is Basic {
         uint256 depositAmount
     ) internal returns (uint256) {
         depositAmount = getUint(getId, depositAmount);
-        if (currencyId == ETH_CURRENCY_ID && useUnderlying)
+        if (currencyId == ETH_CURRENCY_ID && useUnderlying) {
-            return
+            // No approval required for ETH so we can return the deposit amount
-                depositAmount == uint256(-1)
+            return depositAmount == MAX_DEPOSIT
-                    ? address(this).balance
+                ? address(this).balance
-                    : depositAmount;
+                : depositAmount;
+        }
 
         address tokenAddress = useUnderlying
             ? getUnderlyingToken(currencyId)
             : getAssetToken(currencyId);
-        if (depositAmount == uint256(-1)) {
+
+        if (depositAmount == MAX_DEPOSIT) {
             depositAmount = TokenInterface(tokenAddress).balanceOf(
                 address(this)
             );
@@ -132,6 +142,7 @@ contract Helpers is Basic {
                 : getAssetToken(currencyId);
     }
 
+    /// @dev Executes a trade action and sets the balance change to setId
     function executeTradeActionWithBalanceChange(
         BalanceActionWithTrades[] memory action,
         uint256 msgValue,
@@ -157,6 +168,7 @@ contract Helpers is Basic {
         }
     }
 
+    /// @dev Executes a balance action and sets the balance change to setId
     function executeActionWithBalanceChange(
         BalanceAction[] memory action,
         uint256 msgValue,

contracts/mainnet/connectors/notional/interface.sol

@@ -66,10 +66,16 @@ struct BalanceAction {
 }
 
 struct Token {
+    // Address of the token
     address tokenAddress;
+    // True if the token has a transfer fee which is used internally to determine
+    // the proper balance change
     bool hasTransferFee;
+    // Decimal precision of the token as a power of 10
     int256 decimals;
+    // Type of token, enumerated above
     TokenType tokenType;
+    // Used internally for tokens that have a collateral cap, zero if there is no cap
     uint256 maxCollateralBalance;
 }