natspec(Reserve): improve the global contract natsepc

pooltogether · Oct 6, 2021 · 089f757 · 089f757
1 parent 3d938ff
commit 089f757
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 12 deletions.
diff --git a/contracts/PrizeFlush.sol b/contracts/PrizeFlush.sol
@@ -8,15 +8,14 @@ import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import "./interfaces/IPrizeFlush.sol";
 
 /**
- * @title  PoolTogether V4 PrizeFlush
- * @author PoolTogether Inc Team
- * @notice The PrizeFlush contract helps capture interest from the PrizePool and move collected funds
-           to a designated PrizeDistributor contract. When deployed the destination, resereve and strategy
-           addresses are set and used as static parameters during every "flush" execution. The parameters can be
-           reset by the Owner if neccesary.
- * @dev    Ultimately the PrizeFlush contract minimizes the amount of time tokens spent in the Reserve contract and
-           executes a predictable token transfer "order of operations" which includes creating the required "interest captured"
-           checkpoint in the Reserve ring buffer.
+    * @title  PoolTogether V4 PrizeFlush
+    * @author PoolTogether Inc Team
+    * @notice The PrizeFlush contract helps capture interest from the PrizePool and move collected funds
+              to a designated PrizeDistributor contract. When deployed the destination, resereve and strategy
+              addresses are set and used as static parameters during every "flush" execution. The parameters can be
+              reset by the Owner if neccesary.
+    * @dev    Ultimately the PrizeFlush contract minimizes the amount of time tokens spend in the Reserve contract by executing
+              a predictable token transfer "order of operations" which includes a critical checkpoint in the Reserve ring buffer.
  */
 contract PrizeFlush is IPrizeFlush, Manageable {
     /// @notice Static destination for captured interest

diff --git a/contracts/Reserve.sol b/contracts/Reserve.sol
@@ -10,9 +10,16 @@ import "./interfaces/IReserve.sol";
 import "./libraries/ObservationLib.sol";
 
 /**
- * @title  PoolTogether V4 Reserve
- * @author PoolTogether Inc Team
- * @notice The Reserve migrates allotments of token distributions.
+    * @title  PoolTogether V4 Reserve
+    * @author PoolTogether Inc Team
+    * @notice The Reserve contract enables historical searches of a token balance increase during a target timerange.
+              As the Reserve contract transfers OUT tokens, the withdraw accumulator is increased. When tokens are
+              transfered IN new checkpoint *can* be created if checkpoint() is called after transfering tokens.
+              By using the reserve and withdraw accumulators to create a new checkpoint, any contract or account
+              can lookup the balance increase of the reserve for a target timerange.   
+    * @dev    By calculating the total held tokens in a speicific time range, contracts that require knowledge 
+              of captured interest during a draw period, can easily call into the Reserve and determininstially
+              determine the newly aqcuired tokens for that time range. 
  */
 contract Reserve is IReserve, Manageable {
     using SafeERC20 for IERC20;