Add natspec comments

Author: k1rill-fedoseev

src/infra/EnergyRedeemer.sol

@@ -27,6 +27,12 @@ contract EnergyRedeemer is IEnergyRedeemer, Ownable {
     event Redeem(address to, uint256 energy, uint256 redeemed);
     event RampR(uint96 initialR, uint96 futureR, uint32 initialTime, uint32 futureTime);
 
+    /**
+     * @param _pool address allowed to perform redemptions.
+     * @param _rewardToken token address which energy is redeemed into.
+     * @param _base constant redemption rate factor.
+     * @param _r start value for dynamic part of redemption rate factor, 18 decimals.
+     */
     constructor(address _pool, address _rewardToken, uint256 _base, uint96 _r) {
         require(uint256(_r) <= type(uint256).max / _base, "EnergyRedeemer: overflow");
 
@@ -36,6 +42,12 @@ contract EnergyRedeemer is IEnergyRedeemer, Ownable {
         (initialR, futureR, initialRTime, futureRTime) = (_r, _r, uint32(block.timestamp), uint32(block.timestamp));
     }
 
+    /**
+     * @dev Starts changing the rewards multiplication factor R linearly over some time period.
+     * Callable only by the contract owner.
+     * @param _futureR target R value.
+     * @param _duration time duration of R increase/decrease process.
+     */
     function rampR(uint96 _futureR, uint32 _duration) external onlyOwner {
         require(uint256(_futureR) <= type(uint256).max / base, "EnergyRedeemer: overflow");
 
@@ -46,6 +58,12 @@ contract EnergyRedeemer is IEnergyRedeemer, Ownable {
         emit RampR(_initialR, _futureR, t, t + _duration);
     }
 
+    /**
+     * @dev Redeems some amount of energy into the fungible token at the current exchange rate.
+     * Callable only by the whitelisted pool address.
+     * @param _to redeemed token receiver.
+     * @param _energy amount of energy to exchange and redeem.
+     */
     function redeem(address _to, uint256 _energy) external {
         require(msg.sender == pool, "EnergyRedeemer: not authorized");
 
@@ -56,6 +74,11 @@ contract EnergyRedeemer is IEnergyRedeemer, Ownable {
         emit Redeem(_to, _energy, redeemAmount);
     }
 
+    /**
+     * @dev Tells the current rewards multiplication factor R.
+     * Takes into account latest rampR operation.
+     * @return R.
+     */
     function R() public view returns (uint96) {
         (uint96 _initialR, uint96 _futureR, uint32 _initialRTime, uint32 _futureRTime) =
             (initialR, futureR, initialRTime, futureRTime);
@@ -71,6 +94,10 @@ contract EnergyRedeemer is IEnergyRedeemer, Ownable {
         return _futureR;
     }
 
+    /**
+     * @dev Tells the current energy redemption rate based on the R value and information from the pool.
+     * @return energy redemption rate (18 decimals).
+     */
     function calculateRedemptionRate() public view returns (uint256) {
         IZkBobAccounting accounting = IZkBobPool(pool).accounting();
 
@@ -84,6 +111,10 @@ contract EnergyRedeemer is IEnergyRedeemer, Ownable {
         return rate;
     }
 
+    /**
+     * @dev Tells the maximum amount of energy available for redemption at the current rate, given available balance.
+     * @return maximum amount of energy this contract can redeem at the current rate.
+     */
     function maxRedeemAmount() external view returns (uint256) {
         uint256 balance = IERC20(rewardToken).balanceOf(address(this));
         return balance * 1 ether / calculateRedemptionRate();