chore: improve comments (#192)

src/Vault.sol

@@ -179,6 +179,7 @@ contract Vault is IVault, VaultToken, Ownable {
         }
     }
 
+    // if settling native, integrators should still call `sync` first to avoid DoS attack vectors
     function _settle(address recipient) internal returns (uint256 paid) {
         (Currency currency, uint256 reservesBefore) = VaultReserve.getVaultReserve();
         if (!currency.isNative()) {

src/interfaces/IVault.sol

@@ -72,7 +72,8 @@ interface IVault is IVaultToken {
     function accountAppBalanceDelta(Currency currency, int128 delta, address settler) external;
 
     /// @notice Called by the user to net out some value owed to the user
-    /// @dev Can also be used as a mechanism for _free_ flash loans
+    /// @dev Will revert if the requested amount is not available, consider using `mint` instead
+    /// @dev Can also be used as a mechanism for free flash loans
     function take(Currency currency, address to, uint256 amount) external;
 
     /// @notice Writes the current ERC20 balance of the specified currency to transient storage

src/libraries/math/UnsafeMath.sol

@@ -6,7 +6,7 @@ pragma solidity ^0.8.0;
 /// @notice Contains methods that perform common math functions but do not do any overflow or underflow checks
 library UnsafeMath {
     /// @notice Returns ceil(x / y)
-    /// @dev division by 0 has unspecified behavior, and must be checked externally
+    /// @dev division by 0 will return 0, and should be checked externally
     /// @param x The dividend
     /// @param y The divisor
     /// @return z The quotient, ceil(x / y)
@@ -17,7 +17,7 @@ library UnsafeMath {
     }
 
     /// @notice Calculates floor(a×b÷denominator)
-    /// @dev division by 0 has unspecified behavior, and must be checked externally
+    /// @dev division by 0 will return 0, and should be checked externally
     /// @param a The multiplicand
     /// @param b The multiplier
     /// @param denominator The divisor

src/pool-bin/libraries/BinHooks.sol

@@ -163,6 +163,8 @@ library BinHooks {
         // A length of 96 bytes is required to return a bytes4, a 32 byte delta, and an LP fee
         if (result.length != 96) revert Hooks.InvalidHookResponse();
 
+        // dynamic fee pools that want to override the cache fee, return a valid fee with the override flag. If override flag
+        // is set but an invalid fee is returned, the transaction will revert. Otherwise the current LP fee will be used
         if (key.fee.isDynamicLPFee()) {
             lpFeeOverride = result.parseFee();
         }

src/pool-cl/interfaces/ICLHooks.sol

@@ -93,7 +93,7 @@ interface ICLHooks is IHooks {
     /// @param sender The initial msg.sender for the remove liquidity call
     /// @param key The key for the pool
     /// @param params The parameters for removing liquidity
-    /// @param delta The caller's balance delta after adding liquidity; the sum of principal delta, fees accrued, and hook delta
+    /// @param delta The caller's balance delta after remvoing liquidity; the sum of principal delta, fees accrued, and hook delta
     /// @param feesAccrued The fees accrued since the last time fees were collected from this position
     /// @param hookData Arbitrary data handed into the PoolManager by the liquidty provider to be be passed on to the hook
     /// @return bytes4 The function selector for the hook

src/pool-cl/libraries/CLHooks.sol

@@ -140,6 +140,8 @@ library CLHooks {
         // A length of 96 bytes is required to return a bytes4, a 32 byte delta, and an LP fee
         if (result.length != 96) revert Hooks.InvalidHookResponse();
 
+        // dynamic fee pools that want to override the cache fee, return a valid fee with the override flag. If override flag
+        // is set but an invalid fee is returned, the transaction will revert. Otherwise the current LP fee will be used
         if (key.fee.isDynamicLPFee()) {
             lpFeeOverride = result.parseFee();
         }

src/pool-cl/libraries/Tick.sol

@@ -54,6 +54,7 @@ library Tick {
     function tickSpacingToMaxLiquidityPerTick(int24 tickSpacing) internal pure returns (uint128 result) {
         // Equivalent to v3 but in assembly for gas efficiency:
         // int24 minTick = (TickMath.MIN_TICK / tickSpacing);
+        // if (TickMath.MIN_TICK  % tickSpacing != 0) minTick--;
         // int24 maxTick = (TickMath.MAX_TICK / tickSpacing);
         // uint24 numTicks = maxTick - minTick + 1;
         // return type(uint128).max / numTicks;
@@ -162,7 +163,8 @@ library Tick {
             }
         }
 
-        // when the lower (upper) tick is crossed left to right (right to left), liquidity must be added (removed)
+        // when the lower (upper) tick is crossed left to right, liquidity must be added (removed)
+        // when the lower (upper) tick is crossed right to left, liquidity must be removed (added)
         int128 liquidityNetAfter = upper ? (liquidityNetBefore - liquidityDelta) : (liquidityNetBefore + liquidityDelta);
 
         // update two members in one go