Renamed MixinEpoch -> MixinScheduler

contracts/staking/contracts/src/Staking.sol

@@ -21,7 +21,7 @@ pragma solidity ^0.5.9;
 import "./core/MixinExchange.sol";
 import "./core/MixinZrxVault.sol";
 import "./core/MixinRewardVault.sol";
-import "./core/MixinEpoch.sol";
+import "./core/MixinScheduler.sol";
 import "./core/MixinStakeBalances.sol";
 import "./core/MixinStake.sol";
 import "./core/MixinPools.sol";
@@ -34,7 +34,7 @@ contract Staking is
     MixinDeploymentConstants,
     MixinConstants,
     MixinStorage,
-    MixinEpoch,
+    MixinScheduler,
     MixinRewardVault,
     MixinZrxVault,
     MixinExchange,

contracts/staking/contracts/src/core/MixinFees.sol

@@ -24,7 +24,7 @@ import "../immutable/MixinStorage.sol";
 import "../immutable/MixinConstants.sol";
 import "../interfaces/IStakingEvents.sol";
 import "./MixinStakeBalances.sol";
-import "./MixinEpoch.sol";
+import "./MixinScheduler.sol";
 import "./MixinPools.sol";
 import "./MixinExchange.sol";
 import "./MixinRewardVault.sol";
@@ -35,7 +35,7 @@ contract MixinFees is
     IStakingEvents,
     MixinConstants,
     MixinStorage,
-    MixinEpoch,
+    MixinScheduler,
     MixinRewardVault,
     MixinExchange,
     MixinStakeBalances,

contracts/staking/contracts/src/core/MixinScheduler.sol

@@ -25,7 +25,7 @@ import "../immutable/MixinStorage.sol";
 import "../interfaces/IStructs.sol";
 
 
-contract MixinEpoch is
+contract MixinScheduler is
     MixinConstants,
     MixinStorage
 {
@@ -33,55 +33,14 @@ contract MixinEpoch is
     using LibSafeMath for uint256;
     using LibSafeMath64 for uint64;
 
-    /// @dev returns the current epoch in seconds
-    function getEpochPeriodInSeconds()
-        public
-        pure
-        returns (uint64)
-    {
-        return EPOCH_PERIOD_IN_SECONDS;
-    }
-
-    function getTimelockPeriodInEpochs()
-        public
-        pure
-        returns (uint64)
-    {
-        return TIMELOCK_PERIOD_IN_EPOCHS;
-    }
-
-    function getCurrentEpochStartTimeInSeconds()
-        public
-        view
-        returns (uint64)
-    {
-        return currentEpochStartTimeInSeconds;
-    }
-
-    function getCurrentTimelockPeriodStartEpoch()
-        public
-        view
-        returns (uint64)
-    {
-        return currentTimelockPeriodStartEpoch;
-    }
-
-    function getCurrentEpochEndTimeInSeconds()
-        public
-        view
-        returns (uint64)
-    {
-        return getCurrentEpochStartTimeInSeconds()._add(getEpochPeriodInSeconds());
-    }
-
-    function getCurrentTimelockPeriodEndEpoch()
-        public
-        view
-        returns (uint64)
-    {
-        return getCurrentTimelockPeriodStartEpoch()._add(getTimelockPeriodInEpochs());
-    }
+    /// @dev This mixin contains logic for time-based scheduling.
+    /// All processes in the system are segmented into time intervals, called epochs.
+    /// Epochs have a fixed minimum time period that is configured when this contract is deployed.
+    /// The current epoch only changes by calling this contract, which can be invoked by anyone.
+    /// Epochs serve as the basis for all other time intervals, which provides a more stable
+    /// and consistent scheduling metric than time. Timelocks, for example, are measured in epochs.
 
+    /// @dev Returns the current epoch.
     function getCurrentEpoch()
         public
         view
@@ -90,6 +49,38 @@ contract MixinEpoch is
         return currentEpoch;
     }
 
+    /// @dev Returns the current epoch period, measured in seconds.
+    ///      Epoch period = [startTimeInSeconds..endTimeInSeconds)
+    function getEpochPeriodInSeconds()
+        public
+        pure
+        returns (uint64)
+    {
+        return EPOCH_PERIOD_IN_SECONDS;
+    }
+
+    /// @dev Returns the start time in seconds of the current epoch.
+    ///      Epoch period = [startTimeInSeconds..endTimeInSeconds)
+    function getCurrentEpochStartTimeInSeconds()
+        public
+        view
+        returns (uint64)
+    {
+        return currentEpochStartTimeInSeconds;
+    }
+
+    /// @dev Returns the earliest end time in seconds of this epoch.
+    ///      The next epoch can begin once this time is reached.  
+    ///      Epoch period = [startTimeInSeconds..endTimeInSeconds)
+    function getCurrentEpochEarliestEndTimeInSeconds()
+        public
+        view
+        returns (uint64)
+    {
+        return getCurrentEpochStartTimeInSeconds()._add(getEpochPeriodInSeconds());
+    }
+
+    /// @dev Returns the current timelock period
     function getCurrentTimelockPeriod()
         public
         view
@@ -98,6 +89,39 @@ contract MixinEpoch is
         return currentTimelockPeriod;
     }
 
+    /// @dev Returns the length of a timelock period, measured in epochs.
+    ///      Timelock period = [startEpoch..endEpoch)
+    function getTimelockPeriodInEpochs()
+        public
+        pure
+        returns (uint64)
+    {
+        return TIMELOCK_PERIOD_IN_EPOCHS;
+    }
+
+    /// @dev Returns the epoch that the current timelock period started at.
+    ///      Timelock period = [startEpoch..endEpoch)
+    function getCurrentTimelockPeriodStartEpoch()
+        public
+        view
+        returns (uint64)
+    {
+        return currentTimelockPeriodStartEpoch;
+    }
+
+    /// @dev Returns the epoch that the current timelock period will end.
+    ///      Timelock period = [startEpoch..endEpoch)
+    function getCurrentTimelockPeriodEndEpoch()
+        public
+        view
+        returns (uint64)
+    {
+        return getCurrentTimelockPeriodStartEpoch()._add(getTimelockPeriodInEpochs());
+    }
+
+    /// @dev Moves to the next epoch, given the current epoch period has ended.
+    ///      Time intervals that are measured in epochs (like timelocks) are also incremented, given
+    ///      their periods have ended.
     function _goToNextEpoch()
         internal
     {

contracts/staking/contracts/src/core/MixinStake.sol

@@ -25,7 +25,7 @@ import "../immutable/MixinStorage.sol";
 import "../interfaces/IStakingEvents.sol";
 import "./MixinZrxVault.sol";
 import "./MixinRewardVault.sol";
-import "./MixinEpoch.sol";
+import "./MixinScheduler.sol";
 import "./MixinStakeBalances.sol";
 
 
@@ -33,7 +33,7 @@ contract MixinStake is
     IStakingEvents,
     MixinConstants,
     MixinStorage,
-    MixinEpoch,
+    MixinScheduler,
     MixinRewardVault,
     MixinZrxVault,
     MixinStakeBalances

contracts/staking/contracts/src/core/MixinStakeBalances.sol

@@ -23,13 +23,13 @@ import "../libs/LibSafeMath.sol";
 import "../interfaces/IStructs.sol";
 import "../immutable/MixinConstants.sol";
 import "../immutable/MixinStorage.sol";
-import "./MixinEpoch.sol";
+import "./MixinScheduler.sol";
 
 
 contract MixinStakeBalances is
     MixinConstants,
     MixinStorage,
-    MixinEpoch
+    MixinScheduler
 {
 
     using LibSafeMath for uint256;