docs: document constructor and minor improvements

contracts/OffsetHelper.sol

@@ -15,36 +15,49 @@ import "hardhat/console.sol";
  * @notice Helper functions that simplify the carbon offsetting (retirement)
  * process.
  *
- * Retiring carbon tokens normally requires multiple steps and interactions
- * with Toucan Protocol's main contracts:
+ * Retiring carbon tokens requires multiple steps and interactions with
+ * Toucan Protocol's main contracts:
  * 1. Obtain a Toucan pool token such as BCT or NCT (by performing a token
  *    swap).
  * 2. Redeem the pool token for a TCO2 token.
  * 3. Retire the TCO2 token.
  *
  * These steps are combined in each of the following "auto offset" methods
  * implemented in `OffsetHelper` to allow a retirement within one transaction:
- * - `autoOffsetUsingPoolToken()` if the user has already owns a Toucan pool
+ * - `autoOffsetUsingPoolToken()` if the user already owns a Toucan pool
  *   token such as BCT or NCT,
  * - `autoOffsetUsingETH()` if the user would like to perform a retirement
  *   using MATIC,
  * - `autoOffsetUsingToken()` if the user would like to perform a retirement
  *   using an ERC20 token: USDC, WETH or WMATIC.
  *
  * In these methods, "auto" refers to the fact that these methods use
- * `autoRedeem` in order to automatically choose a TCO2 token corresponding
+ * `autoRedeem()` in order to automatically choose a TCO2 token corresponding
  * to the oldest tokenized carbon project in the specfified token pool.
- * There are no fees incurred by the user when using `autoRedeem`.
+ * There are no fees incurred by the user when using `autoRedeem()`, i.e., the
+ * user receives 1 TCO2 token for each pool token (BCT/NCT) redeemed.
  *
- * There are two read helper functions `calculateNeededETHAmount()` and
- * `calculateNeededTokenAmount()` that can be used before calling
- * `autoOffsetUsingETH()` and `autoOffsetUsingToken()`, to determine how MATIC,
- * respectively how much of the ERC20 token must be sent to the `OffsetHelper`
- * contract in order to retire the specified amount of carbon.
+ * There are two `view` helper functions `calculateNeededETHAmount()` and
+ * `calculateNeededTokenAmount()` that should be called before using
+ * `autoOffsetUsingETH()` and `autoOffsetUsingToken()`, to determine how much
+ *  MATIC, respectively how much of the ERC20 token must be sent to the
+ * `OffsetHelper` contract in order to retire the specified amount of carbon.
  */
 contract OffsetHelper is OffsetHelperStorage {
     using SafeERC20 for IERC20;
 
+    /**
+     * @notice Contract constructor. Should specify arrays of ERC20 symbols and
+     * addresses that can used by the contract.
+     *
+     * @dev See `isEligible()` for a list of tokens that can be used in the
+     * contract. These can be modified after deployment by the contract owner
+     * using `setEligibleTokenAddress()` and `deleteEligibleTokenAddress()`.
+     *
+     * @param _eligibleTokenSymbols A list of token symbols.
+     * @param _eligibleTokenAddresses A list of token addresses corresponding
+     * to the provided token symbols.
+     */
     constructor(
         string[] memory _eligibleTokenSymbols,
         address[] memory _eligibleTokenAddresses
@@ -265,9 +278,9 @@ contract OffsetHelper is OffsetHelperStorage {
     /**
      * @notice Swap eligible ERC20 tokens for Toucan pool tokens (BCT/NCT) on SushiSwap
      * @dev Needs to be approved on the client side
-     * @param _fromToken token to deposit and swap
-     * @param _toToken token to swap for (will be held within contract)
-     * @param _amount amount of NCT / BCT wanted
+     * @param _fromToken The ERC20 oken to deposit and swap
+     * @param _toToken The token to swap for (will be held within contract)
+     * @param _amount The required amount of the Toucan pool token (NCT/BCT)
      */
     function swap(
         address _fromToken,
@@ -358,8 +371,8 @@ contract OffsetHelper is OffsetHelperStorage {
 
     /**
      * @notice Swap MATIC for Toucan pool tokens (BCT/NCT) on SushiSwap
-     * @param _toToken token to swap for (will be held within contract)
-     * @param _amount amount of NCT / BCT wanted
+     * @param _toToken Token to swap for (will be held within contract)
+     * @param _amount Amount of NCT / BCT wanted
      */
     function swap(address _toToken, uint256 _amount) public payable {
         // check tokens
@@ -403,7 +416,7 @@ contract OffsetHelper is OffsetHelperStorage {
     }
 
     /**
-     * @notice allow users to withdraw tokens they have deposited
+     * @notice Allow users to withdraw tokens they have deposited.
      */
     function withdraw(address _erc20Addr, uint256 _amount) public {
         require(
@@ -416,8 +429,8 @@ contract OffsetHelper is OffsetHelperStorage {
     }
 
     /**
-     * @notice allow people to deposit BCT / NCT
-     * @dev needs to be approved
+     * @notice Allow users to deposit BCT / NCT.
+     * @dev Needs to be approved
      */
     function deposit(address _erc20Addr, uint256 _amount) public {
         require(isRedeemable(_erc20Addr), "Token not eligible");
@@ -427,12 +440,12 @@ contract OffsetHelper is OffsetHelperStorage {
     }
 
     /**
-     * @notice Redeems the specified amount of NCT / BCT for TCO2
-     * @dev needs to be approved on the client side
-     * @param _fromToken could be the address of NCT or BCT
-     * @param _amount amount to redeem
-     * @return tco2s an array of the TCO2 addresses that were redeemed
-     * @return amounts an array of the amounts of each TCO2 that were redeemed
+     * @notice Redeems the specified amount of NCT / BCT for TCO2.
+     * @dev Needs to be approved on the client side
+     * @param _fromToken Could be the address of NCT or BCT
+     * @param _amount Amount to redeem
+     * @return tco2s An array of the TCO2 addresses that were redeemed
+     * @return amounts An array of the amounts of each TCO2 that were redeemed
      */
     function autoRedeem(address _fromToken, uint256 _amount)
         public
@@ -463,8 +476,9 @@ contract OffsetHelper is OffsetHelperStorage {
 
     /**
      * @notice Retire the specified TCO2 tokens.
-     * @param _tco2s the addresses of the TCO2s to retire
-     * @param _amounts the amounts to retire from the matching TCO2
+     * @param _tco2s The addresses of the TCO2s to retire
+     * @param _amounts The amounts to retire from each of the corresponding
+     * TCO2 addresses
      */
     function autoRetire(address[] memory _tco2s, uint256[] memory _amounts)
         public
@@ -496,9 +510,9 @@ contract OffsetHelper is OffsetHelperStorage {
     // ----------------------------------------
 
     /**
-     * @notice you can use this to change or add eligible tokens and their addresses if needed
-     * @param _tokenSymbol symbol of the token to add
-     * @param _address the address of the token to add
+     * @notice Change or add eligible tokens and their addresses.
+     * @param _tokenSymbol The symbol of the token to add
+     * @param _address The address of the token to add
      */
     function setEligibleTokenAddress(
         string memory _tokenSymbol,
@@ -508,8 +522,8 @@ contract OffsetHelper is OffsetHelperStorage {
     }
 
     /**
-     * @notice you can use this to delete eligible tokens  if needed
-     * @param _tokenSymbol symbol of the token to add
+     * @notice Delete eligible tokens stored in the contract.
+     * @param _tokenSymbol The symbol of the token to remove
      */
     function deleteEligibleTokenAddress(string memory _tokenSymbol)
         public
@@ -520,8 +534,8 @@ contract OffsetHelper is OffsetHelperStorage {
     }
 
     /**
-     * @notice you can use this to change the TCO2 contracts registry if needed
-     * @param _address the contract registry to use
+     * @notice Change the TCO2 contracts registry.
+     * @param _address The address of the Toucan contract registry to use
      */
     function setToucanContractRegistry(address _address)
         public

docs/OffsetHelper.md

@@ -5,39 +5,52 @@
 Helper functions that simplify the carbon offsetting (retirement)
 process.
 
-Retiring carbon tokens normally requires multiple steps and interactions
-with Toucan Protocol's main contracts:
+Retiring carbon tokens requires multiple steps and interactions with
+Toucan Protocol's main contracts:
 1. Obtain a Toucan pool token such as BCT or NCT (by performing a token
    swap).
 2. Redeem the pool token for a TCO2 token.
 3. Retire the TCO2 token.
 
 These steps are combined in each of the following "auto offset" methods
 implemented in `OffsetHelper` to allow a retirement within one transaction:
-- `autoOffsetUsingPoolToken()` if the user has already owns a Toucan pool
+- `autoOffsetUsingPoolToken()` if the user already owns a Toucan pool
   token such as BCT or NCT,
 - `autoOffsetUsingETH()` if the user would like to perform a retirement
   using MATIC,
 - `autoOffsetUsingToken()` if the user would like to perform a retirement
   using an ERC20 token: USDC, WETH or WMATIC.
 
 In these methods, "auto" refers to the fact that these methods use
-`autoRedeem` in order to automatically choose a TCO2 token corresponding
+`autoRedeem()` in order to automatically choose a TCO2 token corresponding
 to the oldest tokenized carbon project in the specfified token pool.
-There are no fees incurred by the user when using `autoRedeem`.
+There are no fees incurred by the user when using `autoRedeem()`, i.e., the
+user receives 1 TCO2 token for each pool token (BCT/NCT) redeemed.
 
-There are two read helper functions `calculateNeededETHAmount()` and
-`calculateNeededTokenAmount()` that can be used before calling
-`autoOffsetUsingETH()` and `autoOffsetUsingToken()`, to determine how MATIC,
-respectively how much of the ERC20 token must be sent to the `OffsetHelper`
-contract in order to retire the specified amount of carbon.
+There are two `view` helper functions `calculateNeededETHAmount()` and
+`calculateNeededTokenAmount()` that should be called before using
+`autoOffsetUsingETH()` and `autoOffsetUsingToken()`, to determine how much
+ MATIC, respectively how much of the ERC20 token must be sent to the
+`OffsetHelper` contract in order to retire the specified amount of carbon.
 
 ### constructor
 
 ```solidity
 constructor(string[] _eligibleTokenSymbols, address[] _eligibleTokenAddresses) public
 ```
 
+Contract constructor. Should specify arrays of ERC20 symbols and
+addresses that can used by the contract.
+
+_See `isEligible()` for a list of tokens that can be used in the
+contract. These can be modified after deployment by the contract owner
+using `setEligibleTokenAddress()` and `deleteEligibleTokenAddress()`._
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| _eligibleTokenSymbols | string[] | A list of token symbols. |
+| _eligibleTokenAddresses | address[] | A list of token addresses corresponding to the provided token symbols. |
+
 ### Redeemed
 
 ```solidity
@@ -222,9 +235,9 @@ _Needs to be approved on the client side_
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| _fromToken | address | token to deposit and swap |
-| _toToken | address | token to swap for (will be held within contract) |
-| _amount | uint256 | amount of NCT / BCT wanted |
+| _fromToken | address | The ERC20 oken to deposit and swap |
+| _toToken | address | The token to swap for (will be held within contract) |
+| _amount | uint256 | The required amount of the Toucan pool token (NCT/BCT) |
 
 ### fallback
 
@@ -266,46 +279,46 @@ Swap MATIC for Toucan pool tokens (BCT/NCT) on SushiSwap
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| _toToken | address | token to swap for (will be held within contract) |
-| _amount | uint256 | amount of NCT / BCT wanted |
+| _toToken | address | Token to swap for (will be held within contract) |
+| _amount | uint256 | Amount of NCT / BCT wanted |
 
 ### withdraw
 
 ```solidity
 function withdraw(address _erc20Addr, uint256 _amount) public
 ```
 
-allow users to withdraw tokens they have deposited
+Allow users to withdraw tokens they have deposited.
 
 ### deposit
 
 ```solidity
 function deposit(address _erc20Addr, uint256 _amount) public
 ```
 
-allow people to deposit BCT / NCT
+Allow users to deposit BCT / NCT.
 
-_needs to be approved_
+_Needs to be approved_
 
 ### autoRedeem
 
 ```solidity
 function autoRedeem(address _fromToken, uint256 _amount) public returns (address[] tco2s, uint256[] amounts)
 ```
 
-Redeems the specified amount of NCT / BCT for TCO2
+Redeems the specified amount of NCT / BCT for TCO2.
 
-_needs to be approved on the client side_
+_Needs to be approved on the client side_
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| _fromToken | address | could be the address of NCT or BCT |
-| _amount | uint256 | amount to redeem |
+| _fromToken | address | Could be the address of NCT or BCT |
+| _amount | uint256 | Amount to redeem |
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| tco2s | address[] | an array of the TCO2 addresses that were redeemed |
-| amounts | uint256[] | an array of the amounts of each TCO2 that were redeemed |
+| tco2s | address[] | An array of the TCO2 addresses that were redeemed |
+| amounts | uint256[] | An array of the amounts of each TCO2 that were redeemed |
 
 ### autoRetire
 
@@ -317,43 +330,43 @@ Retire the specified TCO2 tokens.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| _tco2s | address[] | the addresses of the TCO2s to retire |
-| _amounts | uint256[] | the amounts to retire from the matching TCO2 |
+| _tco2s | address[] | The addresses of the TCO2s to retire |
+| _amounts | uint256[] | The amounts to retire from each of the corresponding TCO2 addresses |
 
 ### setEligibleTokenAddress
 
 ```solidity
 function setEligibleTokenAddress(string _tokenSymbol, address _address) public virtual
 ```
 
-you can use this to change or add eligible tokens and their addresses if needed
+Change or add eligible tokens and their addresses.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| _tokenSymbol | string | symbol of the token to add |
-| _address | address | the address of the token to add |
+| _tokenSymbol | string | The symbol of the token to add |
+| _address | address | The address of the token to add |
 
 ### deleteEligibleTokenAddress
 
 ```solidity
 function deleteEligibleTokenAddress(string _tokenSymbol) public virtual
 ```
 
-you can use this to delete eligible tokens  if needed
+Delete eligible tokens stored in the contract.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| _tokenSymbol | string | symbol of the token to add |
+| _tokenSymbol | string | The symbol of the token to remove |
 
 ### setToucanContractRegistry
 
 ```solidity
 function setToucanContractRegistry(address _address) public virtual
 ```
 
-you can use this to change the TCO2 contracts registry if needed
+Change the TCO2 contracts registry.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| _address | address | the contract registry to use |
+| _address | address | The address of the Toucan contract registry to use |