natspec(General): updated natspec in the interface files

contracts/DrawPrize.sol

@@ -24,7 +24,7 @@ contract DrawPrize is IDrawPrize, Ownable {
 
     /* ============ Global Variables ============ */
 
-    /// @notice The Draw Calculator to use
+    /// @notice DrawCalculator address
     IDrawCalculator internal drawCalculator;
 
     /// @notice Token address
@@ -37,8 +37,8 @@ contract DrawPrize is IDrawPrize, Ownable {
 
     /**
      * @notice Initialize DrawPrize smart contract.
-     * @param _owner           Address of the DrawPrize owner
-     * @param _token           Token address
+     * @param _owner          Owner address
+     * @param _token          Token address
      * @param _drawCalculator DrawCalculator address
      */
     constructor(
@@ -87,6 +87,22 @@ contract DrawPrize is IDrawPrize, Ownable {
         return totalPayout;
     }
 
+    /// @inheritdoc IDrawPrize
+    function withdrawERC20(
+        IERC20 _erc20Token,
+        address _to,
+        uint256 _amount
+    ) external override onlyOwner returns (bool) {
+        require(_to != address(0), "DrawPrize/recipient-not-zero-address");
+        require(address(_erc20Token) != address(0), "DrawPrize/ERC20-not-zero-address");
+
+        _erc20Token.safeTransfer(_to, _amount);
+
+        emit ERC20Withdrawn(_erc20Token, _to, _amount);
+
+        return true;
+    }
+
     /// @inheritdoc IDrawPrize
     function getDrawCalculator() external view override returns (IDrawCalculator) {
         return drawCalculator;
@@ -156,26 +172,4 @@ contract DrawPrize is IDrawPrize, Ownable {
         token.safeTransfer(_to, _amount);
     }
 
-    /**
-     * @notice Transfer ERC20 tokens out of this contract.
-     * @dev    This function is only callable by the owner.
-     * @param _erc20Token ERC20 token to transfer.
-     * @param _to Recipient of the tokens.
-     * @param _amount Amount of tokens to transfer.
-     * @return true if operation is successful.
-     */
-    function withdrawERC20(
-        IERC20 _erc20Token,
-        address _to,
-        uint256 _amount
-    ) external override onlyOwner returns (bool) {
-        require(_to != address(0), "DrawPrize/recipient-not-zero-address");
-        require(address(_erc20Token) != address(0), "DrawPrize/ERC20-not-zero-address");
-
-        _erc20Token.safeTransfer(_to, _amount);
-
-        emit ERC20Withdrawn(_erc20Token, _to, _amount);
-
-        return true;
-    }
 }

contracts/interfaces/IControlledToken.sol

@@ -4,29 +4,40 @@ pragma solidity 0.8.6;
 
 import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 
-/// @title Controlled ERC20 Token
-/// @notice ERC20 Tokens with a controller for minting & burning
+/** @title IControlledToken
+  * @author PoolTogether Inc Team
+  * @notice ERC20 Tokens with a controller for minting & burning.
+*/
 interface IControlledToken is IERC20 {
-    /// @notice Interface to the contract responsible for controlling mint/burn
+
+    /** 
+        @notice Interface to the contract responsible for controlling mint/burn
+    */
     function controller() external view returns (address);
 
-    /// @notice Allows the controller to mint tokens for a user account
-    /// @dev May be overridden to provide more granular control over minting
-    /// @param user Address of the receiver of the minted tokens
-    /// @param amount Amount of tokens to mint
+    /** 
+      * @notice Allows the controller to mint tokens for a user account
+      * @dev May be overridden to provide more granular control over minting
+      * @param user Address of the receiver of the minted tokens
+      * @param amount Amount of tokens to mint
+    */
     function controllerMint(address user, uint256 amount) external;
 
-    /// @notice Allows the controller to burn tokens from a user account
-    /// @dev May be overridden to provide more granular control over burning
-    /// @param user Address of the holder account to burn tokens from
-    /// @param amount Amount of tokens to burn
+    /** 
+      * @notice Allows the controller to burn tokens from a user account
+      * @dev May be overridden to provide more granular control over burning
+      * @param user Address of the holder account to burn tokens from
+      * @param amount Amount of tokens to burn
+    */
     function controllerBurn(address user, uint256 amount) external;
 
-    /// @notice Allows an operator via the controller to burn tokens on behalf of a user account
-    /// @dev May be overridden to provide more granular control over operator-burning
-    /// @param operator Address of the operator performing the burn action via the controller contract
-    /// @param user Address of the holder account to burn tokens from
-    /// @param amount Amount of tokens to burn
+    /** 
+      * @notice Allows an operator via the controller to burn tokens on behalf of a user account
+      * @dev May be overridden to provide more granular control over operator-burning
+      * @param operator Address of the operator performing the burn action via the controller contract
+      * @param user Address of the holder account to burn tokens from
+      * @param amount Amount of tokens to burn
+    */
     function controllerBurnFrom(
         address operator,
         address user,

contracts/interfaces/IDrawBeacon.sol

@@ -6,6 +6,10 @@ import "@pooltogether/pooltogether-rng-contracts/contracts/RNGInterface.sol";
 import "./IDrawHistory.sol";
 import "../libraries/DrawLib.sol";
 
+/** @title  IDrawBeacon
+  * @author PoolTogether Inc Team
+  * @notice The DrawBeacon interface.
+*/
 interface IDrawBeacon {
     /**
      * @notice Emit when a new DrawHistory has been set.
@@ -15,7 +19,7 @@ interface IDrawBeacon {
 
     /**
      * @notice Emit when a draw has opened.
-     * @param operator             User address responsible for opening draw
+     * @param operator  User address responsible for opening draw
      * @param startedAt Start timestamp
      */
     event BeaconPeriodStarted(address indexed operator, uint64 indexed startedAt);

contracts/interfaces/IDrawCalculator.sol

@@ -9,7 +9,7 @@ import "../DrawPrize.sol";
 import "../libraries/DrawLib.sol";
 
 /**
- * @title  PoolTogether V4 DrawCalculator
+ * @title  PoolTogether V4 IDrawCalculator
  * @author PoolTogether Inc Team
  * @notice The DrawCalculator interface.
  */

contracts/interfaces/IDrawHistory.sol

@@ -4,6 +4,10 @@ pragma solidity 0.8.6;
 
 import "../libraries/DrawLib.sol";
 
+/** @title  IDrawHistory
+  * @author PoolTogether Inc Team
+  * @notice The DrawHistory interface.
+*/
 interface IDrawHistory {
     /**
      * @notice Emit when a new draw has been created.
@@ -13,17 +17,17 @@ interface IDrawHistory {
     event DrawSet(uint32 indexed drawId, DrawLib.Draw draw);
 
     /**
-     * @notice Read a Draw from the draws ring buffer.
-     * @dev    Read a Draw using the Draw.drawId to calculate position in the draws ring buffer.
-     * @param drawId Draw.drawId
+     * @notice Read a Draw from draws ring buffer.
+     * @dev    Read a Draw using the drawId to calculate position in draws ring buffer.
+     * @param drawId drawId
      * @return DrawLib.Draw
      */
     function getDraw(uint32 drawId) external view returns (DrawLib.Draw memory);
 
     /**
-     * @notice Read multiple Draws from the draws ring buffer.
-     * @dev    Read multiple Draws using each Draw.drawId to calculate position in the draws ring buffer.
-     * @param drawIds Array of Draw.drawIds
+     * @notice Read multiple Draws from draws ring buffer.
+     * @dev    Read multiple Draws using each drawId to calculate position in draws ring buffer.
+     * @param drawIds Array of drawIds
      * @return DrawLib.Draw[]
      */
     function getDraws(uint32[] calldata drawIds) external view returns (DrawLib.Draw[] memory);
@@ -38,14 +42,14 @@ interface IDrawHistory {
     function getDrawCount() external view returns (uint32);
 
     /**
-     * @notice Read newest Draw from the draws ring buffer.
+     * @notice Read newest Draw from draws ring buffer.
      * @dev    Uses the nextDrawIndex to calculate the most recently added Draw.
      * @return DrawLib.Draw
      */
     function getNewestDraw() external view returns (DrawLib.Draw memory);
 
     /**
-     * @notice Read oldest Draw from the draws ring buffer.
+     * @notice Read oldest Draw from draws ring buffer.
      * @dev    Finds the oldest Draw by comparing and/or diffing totalDraws with the cardinality.
      * @return DrawLib.Draw
      */
@@ -54,16 +58,16 @@ interface IDrawHistory {
     /**
      * @notice Push Draw onto draws ring buffer history.
      * @dev    Push new draw onto draws history via authorized manager or owner.
-     * @param draw DrawLib.Draw
-     * @return Draw.drawId
+     * @param  draw DrawLib.Draw
+     * @return drawId
      */
     function pushDraw(DrawLib.Draw calldata draw) external returns (uint32);
 
     /**
      * @notice Set existing Draw in draws ring buffer with new parameters.
      * @dev    Updating a Draw should be used sparingly and only in the event an incorrect Draw parameter has been stored.
      * @param newDraw DrawLib.Draw
-     * @return Draw.drawId
+     * @return drawId
      */
     function setDraw(DrawLib.Draw calldata newDraw) external returns (uint32);
 }

contracts/interfaces/IDrawPrize.sol

@@ -5,41 +5,52 @@ import "./IDrawHistory.sol";
 import "./IDrawCalculator.sol";
 import "../libraries/DrawLib.sol";
 
+/** @title  IDrawPrize
+  * @author PoolTogether Inc Team
+  * @notice The DrawPrize interface.
+*/
 interface IDrawPrize {
+
     /**
-     * @notice Emitted when a user has claimed N draw payouts.
-     * @param user        User address receiving draw claim payouts
-     * @param drawId      Draw id that was paid out
+     * @notice Emit when user has claimed token from the PrizeDistributor.
+     * @param user   User address receiving draw claim payouts
+     * @param drawId Draw id that was paid out
      * @param payout Payout for draw
      */
     event ClaimedDraw(address indexed user, uint32 indexed drawId, uint256 payout);
 
     /**
-     * @notice Emitted when a DrawCalculator is set
+     * @notice Emit when DrawCalculator is set.
      * @param calculator DrawCalculator address
      */
     event DrawCalculatorSet(IDrawCalculator indexed calculator);
 
     /**
-     * @notice Emitted when a global Ticket variable is set.
+     * @notice Emit when Token is set.
      * @param token Token address
      */
     event TokenSet(IERC20 indexed token);
 
     /**
-     * @notice Emitted when ERC20 tokens are withdrawn
-     * @param token ERC20 token transferred.
-     * @param to Address that received funds.
+     * @notice Emit when ERC20 tokens are withdrawn.
+     * @param token  ERC20 token transferred.
+     * @param to     Address that received funds.
      * @param amount Amount of tokens transferred.
      */
     event ERC20Withdrawn(IERC20 indexed token, address indexed to, uint256 amount);
 
     /**
-     * @notice Claim a user token payouts via a collection of draw ids and pick indices.
+     * @notice Claim prize payout(s) by submitting valud drawId(s) and winning pick indice(s). The user address
+               is used as the "seed" phrase to generate random numbers.
+     * @dev    The claim function is public and any wallet may execute claim on behalf of another user.
+               Prizes are always paid out to the designated user account and not the caller (msg.sender).
+               Claiming prizes is not limited to a single transaction. Reclaiming can be executed
+               subsequentially if an "optimal" prize was not included in previous claim pick indices. The
+               payout difference for the new claim is calculated during the award process and transfered to user. 
      * @param user    Address of user to claim awards for. Does NOT need to be msg.sender
      * @param drawIds Draw IDs from global DrawHistory reference
      * @param data    The data to pass to the draw calculator
-     * @return Actual claim payout.  If the user has previously claimed a draw, this may be less.
+     * @return Total claim payout. May include calcuations from multiple draws.
      */
     function claim(
         address user,
@@ -48,34 +59,42 @@ interface IDrawPrize {
     ) external returns (uint256);
 
     /**
-     * @notice Read DrawCalculator
-     * @return IDrawCalculator
+        * @notice Read global DrawCalculator address.
+        * @return IDrawCalculator
      */
     function getDrawCalculator() external view returns (IDrawCalculator);
 
     /**
-     * @notice Get the amount that a user has already been paid out for a draw
-     * @param user   User address
-     * @param drawId Draw ID
+        * @notice Get the amount that a user has already been paid out for a draw
+        * @param user   User address
+        * @param drawId Draw ID
      */
     function getDrawPayoutBalanceOf(address user, uint32 drawId) external view returns (uint256);
 
     /**
-     * @notice Read global Ticket variable.
-     * @return IERC20
+        * @notice Read global Ticket address.
+        * @return IERC20
      */
     function getToken() external view returns (IERC20);
 
     /**
-     * @notice Sets DrawCalculator reference for individual draw id.
-     * @param _newCalculator  DrawCalculator address
-     * @return New DrawCalculator address
+        * @notice Sets DrawCalculator reference contract.
+        * @param _newCalculator DrawCalculator address
+        * @return New DrawCalculator address
      */
     function setDrawCalculator(IDrawCalculator _newCalculator) external returns (IDrawCalculator);
 
+    /**
+        * @notice Transfer ERC20 tokens out of contract to recipient address.
+        * @dev    Only callable by contract owner.
+        * @param token  ERC20 token to transfer.
+        * @param to     Recipient of the tokens.
+        * @param amount Amount of tokens to transfer.
+        * @return true if operation is successful.
+    */
     function withdrawERC20(
-        IERC20 _erc20Token,
-        address _to,
-        uint256 _amount
+        IERC20 token,
+        address to,
+        uint256 amount
     ) external returns (bool);
 }