add clarifying comments (#233)

contracts/protocol/Getters.sol

@@ -336,7 +336,7 @@ contract Getters is
         view
         returns (Monetary.Value memory, Monetary.Value memory)
     {
-        return getAccountValuesInternal(account, false);
+        return getAccountValuesInternal(account, /* adjustForLiquidity = */ false);
     }
 
     function getAdjustedAccountValues(
@@ -346,7 +346,7 @@ contract Getters is
         view
         returns (Monetary.Value memory, Monetary.Value memory)
     {
-        return getAccountValuesInternal(account, true);
+        return getAccountValuesInternal(account, /* adjustForLiquidity = */ true);
     }
 
     function getAccountBalances(

contracts/protocol/impl/OperationImpl.sol

@@ -631,7 +631,7 @@ library OperationImpl {
         // verify liquidatable
         if (Account.Status.Liquid != state.getStatus(args.liquidAccount)) {
             Require.that(
-                !state.isCollateralized(args.liquidAccount, cache, false),
+                !state.isCollateralized(args.liquidAccount, cache, /* requireMinBorrow = */ false),
                 FILE,
                 "Unliquidatable account",
                 args.liquidAccount.owner,
@@ -848,6 +848,10 @@ library OperationImpl {
 
     // ============ Private Functions ============
 
+    /**
+     * For the purposes of liquidation or vaporization, gets the value-equivalent amount of heldWei
+     * given owedWei and the (spread-adjusted) prices of each asset.
+     */
     function _owedWeiToHeldWei(
         Types.Wei memory owedWei,
         Monetary.Price memory heldPrice,
@@ -863,6 +867,10 @@ library OperationImpl {
         });
     }
 
+    /**
+     * For the purposes of liquidation or vaporization, gets the value-equivalent amount of owedWei
+     * given heldWei and the (spread-adjusted) prices of each asset.
+     */
     function _heldWeiToOwedWei(
         Types.Wei memory heldWei,
         Monetary.Price memory heldPrice,
@@ -878,6 +886,12 @@ library OperationImpl {
         });
     }
 
+    /**
+     * Attempts to vaporize an account's balance using the excess tokens in the protocol. Returns a
+     * bool and a wei value. The boolean is true if and only if the balance was fully vaporized. The
+     * Wei value is how many excess tokens were used to partially or fully vaporize the account's
+     * negative balance.
+     */
     function _vaporizeUsingExcess(
         Storage.State storage state,
         Actions.VaporizeArgs memory args
@@ -887,21 +901,26 @@ library OperationImpl {
     {
         Types.Wei memory excessWei = state.getNumExcessTokens(args.owedMarket);
 
+        // There are no excess funds, return zero
         if (!excessWei.isPositive()) {
             return (false, Types.zeroWei());
         }
 
         Types.Wei memory maxRefundWei = state.getWei(args.vaporAccount, args.owedMarket);
         maxRefundWei.sign = true;
 
+        // The account is fully vaporizable using excess funds
         if (excessWei.value >= maxRefundWei.value) {
             state.setPar(
                 args.vaporAccount,
                 args.owedMarket,
                 Types.zeroPar()
             );
             return (true, maxRefundWei);
-        } else {
+        }
+
+        // The account is only partially vaporizable using excess funds
+        else {
             state.setParFromDeltaWei(
                 args.vaporAccount,
                 args.owedMarket,
@@ -911,6 +930,10 @@ library OperationImpl {
         }
     }
 
+    /**
+     * Returns the (spread-adjusted) prices of two assets for the purposes of liquidation or
+     * vaporization.
+     */
     function _getLiquidationPrices(
         Storage.State storage state,
         Cache.MarketCache memory cache,

contracts/protocol/lib/Cache.sol

@@ -47,6 +47,9 @@ library Cache {
 
     // ============ Setter Functions ============
 
+    /**
+     * Initializes an empty cache for some given number of total markets.
+     */
     function create(
         uint256 numMarkets
     )
@@ -59,6 +62,10 @@ library Cache {
         });
     }
 
+    /**
+     * Adds market information (price and total borrowed par if the market is closing) to the cache.
+     * Returns true if the market information did not previously exist in the cache.
+     */
     function addMarket(
         MarketCache memory cache,
         Storage.State storage state,

contracts/protocol/lib/Storage.sol

@@ -361,10 +361,11 @@ library Storage {
         view
         returns (bool)
     {
+        // get account values (adjusted for liquidity)
         (
             Monetary.Value memory supplyValue,
             Monetary.Value memory borrowValue
-        ) = state.getAccountValues(account, cache, true);
+        ) = state.getAccountValues(account, cache, /* adjustForLiquidity = */ true);
 
         if (borrowValue.value == 0) {
             return true;

contracts/protocol/lib/Types.sol

@@ -45,7 +45,7 @@ library Types {
     }
 
     struct AssetAmount {
-        bool sign;
+        bool sign; // true if positive
         AssetDenomination denomination;
         AssetReference ref;
         uint256 value;
@@ -59,7 +59,7 @@ library Types {
     }
 
     struct Par {
-        bool sign;
+        bool sign; // true if positive
         uint128 value;
     }
 
@@ -172,7 +172,7 @@ library Types {
     // ============ Wei (Token Amount) ============
 
     struct Wei {
-        bool sign;
+        bool sign; // true if positive
         uint256 value;
     }