WIP: update natspec and remove old commented vars

src/GovernanceStaker.sol

@@ -95,7 +95,20 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce
   /// @param balance The deposit's staked balance.
   /// @param owner The owner of this deposit.
   /// @param delegatee The governance delegate who receives the voting weight for this deposit.
-  /// @param beneficiary The address that accrues staking rewards earned by this deposit.
+  /// @param beneficiary The address which has the right to withdraw rewards earned by this
+  /// deposit.
+  /// @param earningPower The "power" this deposit has as it pertains to earning rewards, which
+  /// accrue to this deposit at a rate proportional to its share of the total earning power of the
+  /// system.
+  /// @param rewardPerTokenCheckpoint Checkpoint of the reward per token accumulator for this
+  /// deposit. It represents the value of the global accumulator at the last time a given deposit's
+  /// rewards were calculated and stored. The difference between the global value and this value
+  /// can be used to calculate the interim rewards earned by given deposit.
+  /// @param scaledUnclaimedRewardCheckpoint Checkpoint of the unclaimed rewards earned by a given
+  /// deposit with the scale factor included. This value is stored any time an action is taken that
+  /// specifically impacts the rate at which rewards are earned by a given deposit. Total unclaimed
+  /// rewards for a deposit are thus this value plus all rewards earned after this checkpoint was
+  /// taken. This value is reset to zero when the deposit's rewards are claimed.
   struct Deposit {
     uint256 balance;
     address owner;
@@ -155,9 +168,6 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce
   /// @notice Tracks the total staked by a depositor across all unique deposits.
   mapping(address depositor => uint256 amount) public depositorTotalStaked;
 
-  /// @notice Tracks the total stake actively earning rewards for a given beneficiary account.
-  //mapping(address beneficiary => uint256 amount) public earningPower;
-
   /// @notice Stores the metadata associated with a given deposit.
   mapping(DepositIdentifier depositId => Deposit deposit) public deposits;
 
@@ -178,19 +188,6 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce
   /// @notice Checkpoint value of the global reward per token accumulator.
   uint256 public rewardPerTokenAccumulatedCheckpoint;
 
-  /// @notice Checkpoint of the reward per token accumulator on a per account basis. It represents
-  /// the value of the global accumulator at the last time a given beneficiary's rewards were
-  /// calculated and stored. The difference between the global value and this value can be
-  /// used to calculate the interim rewards earned by given account.
-  // mapping(address account => uint256) public beneficiaryRewardPerTokenCheckpoint;
-
-  /// @notice Checkpoint of the unclaimed rewards earned by a given beneficiary with the scale
-  /// factor included. This value is stored any time an action is taken that specifically impacts
-  /// the rate at which rewards are earned by a given beneficiary account. Total unclaimed rewards
-  /// for an account are thus this value plus all rewards earned after this checkpoint was taken.
-  /// This value is reset to zero when a beneficiary account claims their earned rewards.
-  //mapping(address account => uint256 amount) public scaledUnclaimedRewardCheckpoint;
-
   /// @notice Maps addresses to whether they are authorized to call `notifyRewardAmount`.
   mapping(address rewardNotifier => bool) public isRewardNotifier;
 
@@ -243,16 +240,17 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce
       + (scaledRewardRate * (lastTimeRewardDistributed() - lastCheckpointTime)) / totalStaked;
   }
 
-  /// @notice Live value of the unclaimed rewards earned by a given beneficiary account. It is the
-  /// sum of the last checkpoint value of their unclaimed rewards with the live calculation of the
+  /// @notice Live value of the unclaimed rewards earned by a given deposit. It is the
+  /// sum of the last checkpoint value of the unclaimed rewards with the live calculation of the
   /// rewards that have accumulated for this account in the interim. This value can only increase,
-  /// until it is reset to zero once the beneficiary account claims their unearned rewards.
+  /// until it is reset to zero once the unearned rewards are claimed.
   ///
   /// Note that the contract tracks the unclaimed rewards internally with the scale factor
   /// included, in order to avoid the accrual of precision losses as users takes actions that
   /// cause rewards to be checkpointed. This external helper method is useful for integrations, and
   /// returns the value after it has been scaled down to the reward token's raw decimal amount.
-  /// @return Live value of the unclaimed rewards earned by a given beneficiary account.
+  /// @param _depositId Identifier of the deposit in question.
+  /// @return Live value of the unclaimed rewards earned by a given deposit.
   function unclaimedReward(DepositIdentifier _depositId) external view returns (uint256) {
     return _scaledUnclaimedReward(deposits[_depositId]) / SCALE_FACTOR;
   }
@@ -473,10 +471,10 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce
     _alterDelegatee(deposit, _depositId, _newDelegatee);
   }
 
-  /// @notice For an existing deposit, change the beneficiary to which staking rewards are
-  /// accruing.
+  /// @notice For an existing deposit, change the beneficiary account which has the right to
+  /// withdraw staking rewards.
   /// @param _depositId Unique identifier of the deposit which will have its beneficiary altered.
-  /// @param _newBeneficiary Address of the new rewards beneficiary.
+  /// @param _newBeneficiary Address of the new beneficiary.
   /// @dev The new beneficiary may not be the zero address. The message sender must be the owner of
   /// the deposit.
   function alterBeneficiary(DepositIdentifier _depositId, address _newBeneficiary) external {
@@ -485,10 +483,11 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce
     _alterBeneficiary(deposit, _depositId, _newBeneficiary);
   }
 
-  /// @notice For an existing deposit, change the beneficiary to which staking rewards are
-  /// accruing on behalf of a user, using a signature to validate the user's intent.
+  /// @notice For an existing deposit, change the beneficiary account which has the right to
+  /// withdraw staking rewards accruing on behalf of a user, using a signature to validate the
+  /// user's intent.
   /// @param _depositId Unique identifier of the deposit which will have its beneficiary altered.
-  /// @param _newBeneficiary Address of the new rewards beneficiary.
+  /// @param _newBeneficiary Address of the new beneficiary.
   /// @param _depositor Address of the user on whose behalf this stake is being made.
   /// @param _deadline The timestamp after which the signature should expire.
   /// @param _signature Signature of the user authorizing this stake.
@@ -567,8 +566,9 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce
     _withdraw(deposit, _depositId, _amount);
   }
 
-  /// @notice Claim reward tokens the message sender has earned as a stake beneficiary. Tokens are
-  /// sent to the message sender.
+  /// @notice Claim reward tokens earned by a given deposit. Message sender must be the beneficiary
+  /// address of the deposit. Tokens are sent to the beneficiary address.
+  /// @param _depositId Identifier of the deposit from which accrued rewards will be claimed.
   /// @return Amount of reward tokens claimed.
   function claimReward(DepositIdentifier _depositId) external returns (uint256) {
     Deposit storage deposit = deposits[_depositId];
@@ -578,8 +578,9 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce
     return _claimReward(_depositId, deposit);
   }
 
-  /// @notice Claim earned reward tokens for a beneficiary, using a signature to validate the
-  /// beneficiary's intent. Tokens are sent to the beneficiary.
+  /// @notice Claim reward tokens earned by a given deposit, using a signature to validate the
+  /// caller's intent. The signer must be the beneficiary address of the deposit Tokens are sent to
+  /// the beneficiary.
   /// @param _depositId The identifier for the deposit for which to claim rewards.
   /// @param _deadline The timestamp after which the signature should expire.
   /// @param _signature Signature of the beneficiary authorizing this reward claim.
@@ -830,7 +831,7 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce
   }
 
   /// @notice Checkpoints the unclaimed rewards and reward per token accumulator of a given
-  /// beneficiary account.
+  /// deposit.
   /// @param deposit The deposit for which the reward parameters will be checkpointed.
   /// @dev This is a sensitive internal helper method that must only be called after global rewards
   /// accumulator has been checkpointed. It assumes the global `rewardPerTokenCheckpoint` is up to