Add/improve comments

Author: bbenligiray

packages/convenience/contracts/Convenience.sol

@@ -16,7 +16,7 @@ contract Convenience is Ownable  {
     /// @notice Staking pool of the DAO
     IApi3PoolExtended public immutable api3Pool;
     /// @notice List of ERC20 addresses that will be displayed in the DAO
-    /// treasury
+    /// treasury. The ETH balance will also be displayed by default.
     /// @dev These are set by the owner of this contract
     address[] public erc20Addresses;
     /// @notice Links to the discussion venues for each vote
@@ -74,6 +74,26 @@ contract Convenience is Ownable  {
 
     /// @notice Used by the DAO dashboard client to retrieve user staking data
     /// @param userAddress User address
+    /// @return apr Staking reward APR
+    /// @return api3Supply API3 total supply
+    /// @return totalStake Total amount staked at the pool
+    /// @return totalShares Total pool shares (also represents total voting
+    /// power)
+    /// @return stakeTarget Pool stake target in percentages
+    /// @return userApi3Balance User API3 balance
+    /// @return userStaked Amount of staked tokens the user has at the pool
+    /// @return userUnstaked Amount of non-staked tokens the user has at the
+    /// pool
+    /// @return userVesting Amount of tokens not yet vested to the user (it is
+    /// not withdrawable, similar to `userLocked`)
+    /// @return userUnstakeAmount Amount of tokens the user scheduled to
+    /// unstake
+    /// @return userUnstakeShares Amount of shares the user gave up to schedule
+    /// the unstaking
+    /// @return userUnstakeScheduledFor Time when the scheduled unstake will
+    /// mature
+    /// @return userLocked Amount of rewards the user has received that are not
+    /// withdrawable yet
     function getUserStakingData(address userAddress)
         external
         view
@@ -114,7 +134,24 @@ contract Convenience is Ownable  {
 
     /// @notice Used by the DAO dashboard client to retrieve the treasury and
     /// user delegation data
+    /// @dev In addition to the ERC20 tokens, it returns the ETH balances of
+    /// the treasuries
     /// @param userAddress User address
+    /// @return names ERC20 (+ Ethereum) names
+    /// @return symbols ERC20 (+ Ethereum) symbols
+    /// @return decimals ERC20 (+ Ethereum) decimals
+    /// @return balancesOfPrimaryAgent ERC20 (+ Ethereum) balances of the
+    /// primary agent
+    /// @return balancesOfSecondaryAgent ERC20 (+ Ethereum) balances of the
+    /// secondary agent
+    /// @return proposalVotingPowerThreshold Proposal voting power threshold in
+    /// percentages
+    /// @return userVotingPower Voting power of the user, including delegations
+    /// @return delegatedToUser Voting power delegated to user
+    /// @return delegate Address that the user has delegated to
+    /// @return lastDelegationUpdateTimestamp When the user has last updated
+    /// their delegation
+    /// @return lastProposalTimestamp When the user has last made a proposal
     function getTreasuryAndUserDelegationData(address userAddress)
         external
         view
@@ -171,6 +208,17 @@ contract Convenience is Ownable  {
     /// @param votingAppType Enumerated voting app type (primary or secondary)
     /// @param userAddress User address
     /// @param voteIds Array of vote IDs for which data will be retrieved
+    /// @return startDate Start date of the vote
+    /// @return supportRequired Support required for the vote to pass in
+    /// percentages
+    /// @return minAcceptQuorum Minimum acceptance quorum required for the vote
+    /// to pass in percentages
+    /// @return votingPower Total voting power at the time the vote was created
+    /// @return script The EVMScript that will be run if the vote passes
+    /// @return userVotingPowerAt User's voting power at the time the vote was
+    /// created
+    /// @return discussionUrl Discussion URL set for the vote by the contract
+    /// owner
     function getStaticVoteData(
         VotingAppType votingAppType,
         address userAddress,
@@ -230,6 +278,13 @@ contract Convenience is Ownable  {
     /// @param votingAppType Enumerated voting app type (primary or secondary)
     /// @param userAddress User address
     /// @param voteIds Array of vote IDs for which data will be retrieved
+    /// @return executed If the vote has been executed
+    /// @return yea Total voting power voted for "For"
+    /// @return nay Total voting power voted for "Against"
+    /// @return voterState Vote cast by the user
+    /// @return delegateAt Address the user has delegated to at the time the
+    /// vote was created
+    /// @return delegateState Vote cast by the delegate of the user
     function getDynamicVoteData(
         VotingAppType votingAppType,
         address userAddress,

packages/pool/contracts/StakeUtils.sol

@@ -105,9 +105,8 @@ abstract contract StakeUtils is TransferUtils, IStakeUtils {
     }
 
     /// @notice Called to execute a pre-scheduled unstake
-    /// @dev Note that anyone can execute a matured unstake. This is to allow
-    /// the user to use bots, etc. to execute their unstaking as soon as
-    /// possible.
+    /// @dev Anyone can execute a matured unstake. This is to allow the user to
+    /// use bots, etc. to execute their unstaking as soon as possible.
     /// @param userAddress User address
     /// @return Amount of tokens that are unstaked
     function unstake(address userAddress)
@@ -128,8 +127,9 @@ abstract contract StakeUtils is TransferUtils, IStakeUtils {
         uint256 totalShares = totalShares();
         uint256 unstakeAmount = user.unstakeAmount;
         uint256 unstakeAmountByShares = user.unstakeShares * totalStake / totalShares;
-        // If there was a claim payout in between the scheduling and the actual unstake 
-        // then the amount might be lower than expected at scheduling time
+        // If there was a claim payout in between the scheduling and the actual
+        // unstake then the amount might be lower than expected at scheduling
+        // time
         if (unstakeAmount > unstakeAmountByShares)
         {
             unstakeAmount = unstakeAmountByShares;
@@ -151,8 +151,8 @@ abstract contract StakeUtils is TransferUtils, IStakeUtils {
 
     /// @notice Convenience method to execute an unstake and withdraw to the
     /// user's wallet in a single transaction
-    /// @dev Note that the withdrawal may revert because the user may have less
-    /// than `unstaked` tokens that are withdrawable
+    /// @dev The withdrawal will revert if the user has less than
+    /// `unstakeAmount` tokens that are withdrawable
     function unstakeAndWithdraw()
         external
         override

packages/pool/contracts/StateUtils.sol

@@ -53,8 +53,8 @@ contract StateUtils is IStateUtils {
     uint256 public constant EPOCH_LENGTH = 1 weeks;
 
     /// @notice Number of epochs before the staking rewards get unlocked.
-    /// Hardcoded as 52 epochs, which corresponds to a year with an
-    /// `EPOCH_LENGTH` of 1 week.
+    /// Hardcoded as 52 epochs, which approximately corresponds to a year with
+    /// an `EPOCH_LENGTH` of 1 week.
     uint256 public constant REWARD_VESTING_PERIOD = 52;
 
     // All percentage values are represented as 1e18 = 100%

packages/pool/contracts/TimelockUtils.sol

@@ -6,7 +6,7 @@ import "./interfaces/ITimelockUtils.sol";
 
 /// @title Contract that implements vesting functionality
 /// @dev The TimelockManager contract interfaces with this contract to transfer
-/// API3 tokens that are locked under a vesting schedule
+/// API3 tokens that are locked under a vesting schedule.
 /// This contract keeps its own type definitions, event declarations and state
 /// variables for them to be easier to remove for a subDAO where they will
 /// likely not be used.
@@ -28,7 +28,7 @@ abstract contract TimelockUtils is ClaimUtils, ITimelockUtils {
     /// @notice Called by the TimelockManager contract to deposit tokens on
     /// behalf of a user
     /// @dev This method is only usable by `TimelockManager.sol`.
-    /// It is named as `deposit()` and not `depositByTimelockManager()` for
+    /// It is named as `deposit()` and not `depositAsTimelockManager()` for
     /// example, because the TimelockManager is already deployed and expects
     /// the `deposit(address,uint256,address)` interface.
     /// @param source Token transfer source