docs: improve comments

src/interfaces/IBlue.sol

@@ -234,57 +234,81 @@ interface IBlue is IFlashLender {
     /// @notice Creates `market`.
     function createMarket(Market memory market) external;
 
-    /// @notice Supplies assets to a market.
+    /// @notice Supplies the given `amount` of assets or `shares` to the given `market` on behalf of `onBehalf`,
+    ///         optionally calling back the caller's `onBlueSupply` function with the given `data`.
+    /// @dev Either `amount` or `shares` should be zero.
+    ///      Most usecases should rely on `amount` as an input so the caller
+    ///      is guaranteed to have `amount` tokens pulled from their balance,
+    ///      but the possibility to mint a specific amount of shares is given
+    ///      for full compatibility and precision.
     /// @param market The market to supply assets to.
     /// @param amount The amount of assets to supply.
+    /// @param shares The amount of shares to mint.
     /// @param onBehalf The address that will receive the position.
     /// @param data Arbitrary data to pass to the `onBlueSupply` callback. Pass empty data if not needed.
     function supply(Market memory market, uint256 amount, uint256 shares, address onBehalf, bytes memory data)
         external;
 
-    /// @notice Withdraws assets from a market.
+    /// @notice Withdraws the given `amount` of assets or `shares` from the given `market` on behalf of `onBehalf`.
+    /// @dev Either `amount` or `shares` should be zero.
+    ///      To withdraw the whole position, pass the `shares`'s balance of `onBehalf`.
+    /// @dev If `msg.sender != onBehalf`, `msg.sender` must be authorized to withdraw from `onBehalf`.
     /// @param market The market to withdraw assets from.
-    /// @param onBehalf The address from which to withdraw.
+    /// @param shares The amount of amount to withdraw.
+    /// @param shares The amount of shares to burn.
+    /// @param onBehalf The address of the owner of the withdrawn assets.
     /// @param receiver The address that will receive the withdrawn assets.
-    /// @dev If `msg.sender != onBehalf`, `msg.sender` must be authorized to withdraw from `onBehalf`.
     function withdraw(Market memory market, uint256 amount, uint256 shares, address onBehalf, address receiver)
         external;
 
-    /// @notice Borrows assets from a market.
+    /// @notice Borrows the given `amount` of assets or `shares` from the given `market` on behalf of `onBehalf`.
+    /// @dev Either `amount` or `shares` should be zero.
+    ///      Most usecases should rely on `amount` as an input so the caller
+    ///      is guaranteed to borrow `amount` of tokens,
+    ///      but the possibility to burn a specific amount of shares is given
+    ///      for full compatibility and precision.
     /// @param market The market to borrow assets from.
     /// @param amount The amount of assets to borrow.
-    /// @param onBehalf The address from which to borrow.
-    /// @param receiver The address that will receive the borrowed assets.
+    /// @param shares The amount of shares to mint.
+    /// @param onBehalf The address of the owner of the debt.
+    /// @param receiver The address that will receive the debt.
     /// @dev If `msg.sender != onBehalf`, `msg.sender` must be authorized to withdraw from `onBehalf`.
     function borrow(Market memory market, uint256 amount, uint256 shares, address onBehalf, address receiver)
         external;
 
-    /// @notice Repays assets to a market.
+    /// @notice Repays the given `amount` of assets or `shares` to the given `market` on behalf of `onBehalf`,
+    ///         optionally calling back the caller's `onBlueReplay` function with the given `data`.
+    /// @dev Either `amount` or `shares` should be zero.
+    ///      To repay the whole debt, pass the `shares`'s balance of `onBehalf`.
     /// @param market The market to repay assets to.
-    /// @param onBehalf The address for which to repay.
+    /// @param amount The amount of assets to repay.
+    /// @param shares The amount of shares to burn.
+    /// @param onBehalf The address of the owner of the debt.
     /// @param data Arbitrary data to pass to the `onBlueRepay` callback. Pass empty data if not needed.
     function repay(Market memory market, uint256 amount, uint256 shares, address onBehalf, bytes memory data)
         external;
 
-    /// @notice Supplies collateral to a market.
+    /// @notice Supplies the given `amount` of collateral to the given `market` on behalf of `onBehalf`,
+    ///         optionally calling back the caller's `onBlueSupplyCollateral` function with the given `data`.
+    /// @dev Interests are not accrued since it's not required and it saves gas.
     /// @param market The market to supply collateral to.
     /// @param amount The amount of collateral to supply.
-    /// @param onBehalf The address that will receive the position.
+    /// @param onBehalf The address that will receive the collateral.
     /// @param data Arbitrary data to pass to the `onBlueSupplyCollateral` callback. Pass empty data if not needed.
-    /// @dev Don't accrue interests because it's not required and it saves gas.
     function supplyCollateral(Market memory market, uint256 amount, address onBehalf, bytes memory data) external;
 
-    /// @notice Withdraws collateral from a market.
+    /// @notice Withdraws the given `amount` of collateral from the given `market` on behalf of `onBehalf`.
+    /// @dev If `msg.sender != onBehalf`, `msg.sender` must be authorized to withdraw from `onBehalf`.
     /// @param market The market to withdraw collateral from.
     /// @param amount The amount of collateral to withdraw.
-    /// @param onBehalf The address from which to withdraw.
+    /// @param onBehalf The address of the owner of the collateral.
     /// @param receiver The address that will receive the withdrawn collateral.
-    /// @dev If `msg.sender != onBehalf`, `msg.sender` must be authorized to withdraw from `onBehalf`.
     function withdrawCollateral(Market memory market, uint256 amount, address onBehalf, address receiver) external;
 
-    /// @notice Liquidates a position.
+    /// @notice Liquidates the given `seized` amount to the given `market` of the given `borrower`'s position,
+    ///         optionally calling back the caller's `onBlueLiquidate` function with the given `data`.
     /// @param market The market of the position.
-    /// @param borrower The borrower of the position.
+    /// @param borrower The owner of the position.
     /// @param seized The amount of collateral to seize.
     /// @param data Arbitrary data to pass to the `onBlueLiquidate` callback. Pass empty data if not needed
     function liquidate(Market memory market, address borrower, uint256 seized, bytes memory data) external;