docs: addresses requested changes

src/interfaces/IDebtService.sol

@@ -22,8 +22,8 @@ interface IDebtService is IAdminService {
     /// @param _cAmt The amount of collateral to be supplied (units: C_DECIMALS).
     function addCollateral(uint256 _cAmt) external payable;
 
-    /// @notice Increases the collateral amount for this contract's loan with permit,
-    ///         obviating the need for a separate approve tx. This function can only be used for ERC-2612-compliant tokens.
+    /// @notice Increases the collateral amount for this contract's loan with permit (no separate approve tx).
+    /// @dev This function can only be used for ERC-2612-compliant tokens.
     /// @param _cAmt The amount of collateral to be supplied (units: C_DECIMALS).
     /// @param _deadline The expiration timestamp of the permit.
     /// @param _v The V parameter of ERC712 signature for the permit.
@@ -33,21 +33,21 @@ interface IDebtService is IAdminService {
         external
         payable;
 
-    /// @notice Withdraws collateral token from Aave to specified recipient.
+    /// @notice Withdraws collateral from Aave to the specified recipient.
     /// @param _token The address of the collateral token to be withdrawn (C_TOKEN or B_TOKEN).
     /// @param _amt The amount of collateral to be withdrawn (units: C_DECIMALS or B_DECIMALS).
     /// @param _recipient The recipient of the funds.
     function withdraw(address _token, uint256 _amt, address _recipient) external payable;
 
-    /// @notice Repays any outstanding debt to Aave and transfers remaining collateral from Aave to owner.
+    /// @notice Repays outstanding debt to Aave.
+    /// @dev To pay off entire debt, _dAmt = debtOwed + smallBuffer (to account for interest).
     /// @param _dAmt The amount of debt token to repay to Aave (units: D_DECIMALS).
-    ///              To pay off entire debt, _dAmt = debtOwed + smallBuffer (to account for interest).
     function repay(uint256 _dAmt) external payable;
 
-    /// @notice Repays any outstanding debt to Aave and transfers remaining collateral from Aave to owner,
-    ///         with permit, obviating the need for a separate approve tx. This function can only be used for ERC-2612-compliant tokens.
+    /// @notice Repays outstanding debt to Aave with permit (no separate approve tx).
+    /// @dev This function can only be used for ERC-2612-compliant tokens.
+    /// @dev To pay off entire debt, _dAmt = debtOwed + smallBuffer (to account for interest).
     /// @param _dAmt The amount of debt token to repay to Aave (units: D_DECIMALS).
-    ///              To pay off entire debt, _dAmt = debtOwed + smallBuffer (to account for interest).
     /// @param _deadline The expiration timestamp of the permit.
     /// @param _v The V parameter of ERC712 signature for the permit.
     /// @param _r The R parameter of ERC712 signature for the permit.

src/interfaces/IFeeCollector.sol

@@ -12,7 +12,7 @@ interface IFeeCollector {
     /// @notice The maximum percentage of protocol fees allocated to clients.
     function clientRate() external view returns (uint256);
 
-    /// @notice Returns the take rate of the specified client operator; the percentage of the client rate that the operator keeps.
+    /// @notice Returns the take rate of the specified client operator (% of client rate that the operator keeps).
     /// @dev Example: clientTakeRates[client] = clientTakeRate
     /// @param _client A client operator address.
     /// @return clientTakeRate The percentage of the client rate that the operator keeps.
@@ -31,27 +31,22 @@ interface IFeeCollector {
     /// @return balance The balance for the specified token for the specified client operator.
     function balances(address _client, address _token) external view returns (uint256);
 
-    /// @notice Collects fees from Position contracts when collateral is added.
+    /// @notice Collects fees from Position contracts.
     /// @param _client The address where a client operator will receive protocols fees.
-    /// @param _token The token to collect fees in (the collateral token of the calling Position contract).
+    /// @param _token The token to collect fees in (collateral token or debt token of the calling Position contract).
     /// @param _amt The total amount of fees to collect.
     function collectFees(address _client, address _token, uint256 _amt, uint256 _clientFee) external payable;
 
     /// @notice Withdraw collected fees from this contract.
     /// @param _token The token address to withdraw.
     function clientWithdraw(address _token) external payable;
 
-    /// @notice Allows clients to set the percentage of the clientRate they will receive each revenue-generating tx.
-    ///         Amounts less than 100 will give the calling client's users a protocol fee discount:
-    ///         clientPercentOfProtocolFee = clientRate * _clientTakeRate
-    ///         userPercentOfProtocolFee =  clientRate * (1 - _clientTakeRate)
-    ///         clientFee = protocolFee * clientPercentOfProtocolFee
-    ///         userSavings = protocolFee * userPercentOfProtocolFee
-    /// @param _clientTakeRate The percentage of the clientRate the client will receive each revenue-generating tx (100 = 100%).
+    /// @notice Allows clients to set the percentage of clientRate they receive each revenue-generating tx.
+    /// @dev Amounts less than 100 will give the calling client's users a protocol fee discount.
+    /// @param _clientTakeRate The percentage of clientRate the client receives (100 = 100%).
     function setClientTakeRate(uint256 _clientTakeRate) external payable;
 
-    /// @notice Returns the amount discounted from the protocol fee for using the provided client,
-    ///         and the amount of fees the client will receive.
+    /// @notice Returns discount amount and client fees when using the provided client.
     /// @param _client The address where a client operator will receive protocols fees.
     /// @param _maxFee The maximum amount of fees the protocol will collect.
     /// @return userSavings The amount of fees discounted from the protocol fee.

src/interfaces/IPosition.sol

@@ -11,7 +11,7 @@ interface IPosition is IDebtService {
     **
     ******************************************************************************/
 
-    /// @notice Returns the address of this position's base token (the token that the debt token is swapped for when shorting).
+    /// @notice Returns the address of base token (the token that D_TOKEN is swapped for).
     function B_TOKEN() external view returns (address);
 
     /// @notice Returns the number of decimals this position's base token is denominated in.
@@ -27,18 +27,18 @@ interface IPosition is IDebtService {
     /// @param _cAmt The amount of collateral token to be supplied for this transaction-specific loan (units: C_DECIMALS).
     /// @param _ltv The desired loan-to-value ratio for this transaction-specific loan (ex: 75 is 75%).
     /// @param _swapAmtOutMin The minimum amount of output tokens from swap for the tx to go through.
-    /// @param _poolFee The fee of the Uniswap pool.
+    /// @param _poolFee The fee of the Uniswap pool (3000 = 0.30%).
     /// @param _client The address of the client operator. Use address(0) if not using a client.
     function add(uint256 _cAmt, uint256 _ltv, uint256 _swapAmtOutMin, uint24 _poolFee, address _client)
         external
         payable;
 
-    /// @notice Adds to this contract's position with permit, obviating the need for a separate approve tx.
-    ///         This function can only be used for ERC-2612-compliant tokens.
+    /// @notice Adds to this contract's position with permit (no separate approve tx).
+    /// @dev This function can only be used for ERC-2612-compliant tokens.
     /// @param _cAmt The amount of collateral token to be supplied for this transaction-specific loan (units: C_DECIMALS).
     /// @param _ltv The desired loan-to-value ratio for this transaction-specific loan (ex: 75 is 75%).
     /// @param _swapAmtOutMin The minimum amount of output tokens from swap for the tx to go through.
-    /// @param _poolFee The fee of the Uniswap pool.
+    /// @param _poolFee The fee of the Uniswap pool (3000 = 0.30%).
     /// @param _client The address of the client operator. Use address(0) if not using a client.
     /// @param _deadline The expiration timestamp of the permit.
     /// @param _v The V parameter of ERC712 signature for the permit.
@@ -59,14 +59,14 @@ interface IPosition is IDebtService {
     /// @notice Adds leverage to this contract's position.
     /// @param _dAmt The amount of D_TOKEN to borrow; use position LTV to identify max amount.
     /// @param _swapAmtOutMin The minimum amount of output tokens from swap for the tx to go through.
-    /// @param _poolFee The fee of the Uniswap pool.
+    /// @param _poolFee The fee of the Uniswap pool (3000 = 0.30%).
     /// @param _client The address of the client operator. Use address(0) if not using a client.
     function addLeverage(uint256 _dAmt, uint256 _swapAmtOutMin, uint24 _poolFee, address _client) external payable;
 
-    /// @notice Fully closes the position.
-    /// @param _poolFee The fee of the Uniswap pool.
+    /// @notice Reduces a position based on the amount of B_TOKEN and C_TOKEN withdrawn.
+    /// @param _poolFee The fee of the Uniswap pool (3000 = 0.3%).
     /// @param _exactOutput Whether to swap exact output or exact input (true for exact output, false for exact input).
-    /// @param _swapAmtOutMin The minimum amount of output tokens from swap for the tx to go through (only used if _exactOutput is false, supply 0 if true).
+    /// @param _swapAmtOutMin The min amount of output tokens from swap (supply 0 if _exactOutput = true).
     /// @param _withdrawCAmt The amount of C_TOKEN to withdraw (units: C_DECIMALS).
     /// @param _withdrawBAmt The amount of B_TOKEN to withdraw (units: B_DECIMALS).
     function close(

src/services/AdminService.sol

@@ -24,15 +24,12 @@ contract AdminService is IAdminService {
         OWNER = _owner;
     }
 
-    /// @notice Allows owner to withdraw all of this contract's native token balance.
-    /// @dev This function is only callable by the owner account.
+    /// @inheritdoc IAdminService
     function extractNative() public payable onlyOwner {
         payable(msg.sender).transfer(address(this).balance);
     }
 
-    /// @notice Allows owner to withdraw all of a specified ERC20 token's balance from this contract.
-    /// @dev This function is only callable by the owner account.
-    /// @param _token The address of token to remove.
+    /// @inheritdoc IAdminService
     function extractERC20(address _token) public payable onlyOwner {
         uint256 balance = IERC20(_token).balanceOf(address(this));
 

src/services/DebtService.sol

@@ -53,11 +53,11 @@ contract DebtService is AdminService, IDebtService {
     /// @param _ltv The desired loan-to-value ratio for this transaction-specific loan (ex: 75 is 75%).
     /// @return dAmt The amount of the debt token borrowed (units: D_DECIMALS).
     /// @dev dAmt is calculated as follows:
-    /// c_amt_wei = _cAmt * _C_DEC_CONVERSION (decimals: 18)
-    /// c_amt_usd = c_amt_wei * cPrice (decimals: 18 + 8 => 26)
-    /// debt_amt_usd = c_amt_usd * _ltv / 100 (decimals: 26)
-    /// debt_amt_usd_d_decimals = debt_amt_usd / _D_DEC_CONVERSION (decimals: 26 - (18 - D_DECIMALS))
-    /// dAmt = debt_amt_d_decimals = debt_amt_usd_d_decimals / dPrice (decimals: D_DECIMALS)
+    /// @dev c_amt_wei = _cAmt * _C_DEC_CONVERSION (decimals: 18)
+    /// @dev c_amt_usd = c_amt_wei * cPrice (decimals: 18 + 8 => 26)
+    /// @dev debt_amt_usd = c_amt_usd * _ltv / 100 (decimals: 26)
+    /// @dev debt_amt_usd_d_decimals = debt_amt_usd / _D_DEC_CONVERSION (decimals: 26 - (18 - D_DECIMALS))
+    /// @dev dAmt = debt_amt_d_decimals = debt_amt_usd_d_decimals / dPrice (decimals: D_DECIMALS)
     function _takeLoan(uint256 _cAmt, uint256 _ltv) internal returns (uint256 dAmt) {
         // 1. Supply collateral to Aave
         SafeTransferLib.safeApprove(ERC20(C_TOKEN), AAVE_POOL, _cAmt);
@@ -103,23 +103,14 @@ contract DebtService is AdminService, IDebtService {
         IPool(AAVE_POOL).supply(_bToken, _bAmt, address(this), 0);
     }
 
-    /// @notice Increases the collateral amount backing this contract's loan.
-    /// @dev This function is only callable by the owner account.
-    /// @param _cAmt The amount of collateral to be supplied (units: C_DECIMALS).
+    /// @inheritdoc IDebtService
     function addCollateral(uint256 _cAmt) public payable onlyOwner {
         SafeTransferLib.safeTransferFrom(ERC20(C_TOKEN), msg.sender, address(this), _cAmt);
         SafeTransferLib.safeApprove(ERC20(C_TOKEN), AAVE_POOL, _cAmt);
         IPool(AAVE_POOL).supply(C_TOKEN, _cAmt, address(this), 0);
     }
 
-    /// @notice Increases the collateral amount for this contract's loan with permit, obviating the need for a separate approve tx.
-    ///         This function can only be used for ERC-2612-compliant tokens.
-    /// @dev This function is only callable by the owner account.
-    /// @param _cAmt The amount of collateral to be supplied (units: C_DECIMALS).
-    /// @param _deadline The expiration timestamp of the permit.
-    /// @param _v The V parameter of ERC712 signature for the permit.
-    /// @param _r The R parameter of ERC712 signature for the permit.
-    /// @param _s The S parameter of ERC712 signature for the permit.
+    /// @inheritdoc IDebtService
     function addCollateralWithPermit(uint256 _cAmt, uint256 _deadline, uint8 _v, bytes32 _r, bytes32 _s)
         public
         payable
@@ -129,33 +120,18 @@ contract DebtService is AdminService, IDebtService {
         addCollateral(_cAmt);
     }
 
-    /// @notice Withdraws collateral token from Aave to specified recipient.
-    /// @dev This function is only callable by the owner account.
-    /// @param _token The address of the collateral token to be withdrawn (C_TOKEN or B_TOKEN).
-    /// @param _amt The amount of collateral to be withdrawn (units: C_DECIMALS or B_DECIMALS).
-    /// @param _recipient The recipient of the funds.
+    /// @inheritdoc IDebtService
     function withdraw(address _token, uint256 _amt, address _recipient) public payable onlyOwner {
         IPool(AAVE_POOL).withdraw(_token, _amt, _recipient);
     }
 
-    /// @notice Repays any outstanding debt to Aave.
-    /// @dev This function is only callable by the owner account.
-    /// @param _dAmt The amount of debt token to repay to Aave (units: D_DECIMALS).
-    ///              To pay off entire debt, _dAmt = debtOwed + smallBuffer (to account for interest).
+    /// @inheritdoc IDebtService
     function repay(uint256 _dAmt) public payable onlyOwner {
         SafeTransferLib.safeTransferFrom(ERC20(D_TOKEN), msg.sender, address(this), _dAmt);
         _repay(_dAmt);
     }
 
-    /// @notice Repays any outstanding debt to Aave and transfers remaining collateral from Aave to owner,
-    ///         with permit, obviating the need for a separate approve tx. This function can only be used for ERC-2612-compliant tokens.
-    /// @dev This function is only callable by the owner account.
-    /// @param _dAmt The amount of debt token to repay to Aave (units: D_DECIMALS).
-    ///              To pay off entire debt, _dAmt = debtOwed + smallBuffer (to account for interest).
-    /// @param _deadline The expiration timestamp of the permit.
-    /// @param _v The V parameter of ERC712 signature for the permit.
-    /// @param _r The R parameter of ERC712 signature for the permit.
-    /// @param _s The S parameter of ERC712 signature for the permit.
+    /// @inheritdoc IDebtService
     function repayWithPermit(uint256 _dAmt, uint256 _deadline, uint8 _v, bytes32 _r, bytes32 _s)
         public
         payable