Add Documentation

contracts/Epochs/Manager.sol

@@ -11,13 +11,18 @@ import "../Staking/Directory.sol";
 
 contract EpochsManager is Initializable, OwnableUpgradeable {
 
+    /**
+     * @dev This struct will hold all network parameters that will be static
+     * for the entire epoch. This value will be stored in a mapping, where the
+     * key is also the epoch's iteration value.
+     */
     struct Epoch {
         uint256 iteration;
 
         // time related variables
         uint256 startBlock; // Block the epoch was initialized
-        uint256 duration; // Minimum time epoch will be alive measued in number of blocks
-        uint256 endBlock; // Block the epoch ended (and when the next epoch was initialised)
+        uint256 duration; // Minimum time epoch will be alive measured in number of blocks
+        uint256 endBlock; // Block the epoch ended (and when the next epoch was initialized)
                           // Zero here represents the epoch has not yet ended.
 
         // listing variables
@@ -37,19 +42,26 @@ contract EpochsManager is Initializable, OwnableUpgradeable {
 
     TicketingParameters public _ticketingParameters;
 
-    /*
-     * Define all Epoch specific parameters here.
-     * When initializing an epoch, these parameters are read,
-     * along with parameters from the other contracts to create the
-     * new epoch.
-     */
+    // Define all Epoch specific parameters here.
+    // When initializing an epoch, these parameters are read,
+    // along with parameters from the other contracts to create the
+    // new epoch.
 
+    /**
+     * @notice The duration in blocks an epoch will last for.
+     */
     uint256 public epochDuration;
 
-    // Increment this value as each epoch is intialized.
-    // The iteration is also used as the epoch's identifier.
+    /**
+     * @notice The value of the integer used as the current
+     * epoch's identifier. This value is incremented as each epoch
+     * is initialized.
+     */
     uint256 public currentIteration;
 
+    /**
+     * @notice A mapping of all epochs that have been initialized.
+     */
     mapping (uint256 => Epoch) public epochs;
 
     event NewEpoch(uint256 epochId);
@@ -68,6 +80,14 @@ contract EpochsManager is Initializable, OwnableUpgradeable {
         currentIteration = 0;
     }
 
+    /**
+     * @notice Call this to initialize the next epoch. This is only callable
+     * by the owner of the Sylo contracts. On success, a `NewEpoch` event
+     * will be emitted.
+     * @dev The function will read the current set of network parameters, and store
+     * the parameters in a new Epoch struct. The end block of the current epoch
+     * will also be set to a non-zero value.
+     */
     function initializeEpoch() public returns (uint256) {
         Epoch storage current = epochs[currentIteration];
 
@@ -103,14 +123,28 @@ contract EpochsManager is Initializable, OwnableUpgradeable {
         return epochId;
     }
 
-    function getCurrentActiveEpoch() public view returns (Epoch memory epoch) {
+    /**
+     * @notice Retrieve the parameters for the current epoch.
+     * @return The current Epoch parameters.
+     */
+    function getCurrentActiveEpoch() public view returns (Epoch memory) {
         return epochs[currentIteration];
     }
 
+    /**
+     * @notice Retrieve the integer value that will be used for the
+     * next epoch id.
+     * @return The next epoch id identifier.
+     */
     function getNextEpochId() public view returns (uint256) {
         return currentIteration + 1;
     }
 
+    /**
+     * @notice Retrieve the epoch parameter for the given id.
+     * @param epochId The id of the epoch to retrieve.
+     * @return The epoch parameters associated with the id.
+     */
     function getEpoch(uint256 epochId) public view returns (Epoch memory) {
         return epochs[epochId];
     }

contracts/Listings.sol

@@ -5,14 +5,19 @@ pragma experimental ABIEncoderV2;
 import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
 import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
 
+/**
+ * @notice This contract manages Listings for Nodes. A Listing is a
+ * set of parameters configured by the Node itself. A Node is required
+ * to have a valid Listing to be able to participate in the network.
+ */
 contract Listings is Initializable, OwnableUpgradeable {
 
     struct Listing {
         // MultiAddr to connect to the account
         string multiAddr;
 
         // Percentage of a tickets value that will be rewarded to
-        // delagated stakers expressed as a fraction of 10000.
+        // delegated stakers expressed as a fraction of 10000.
         // This value is currently locked to the default payout percentage
         // until epochs are implemented.
         uint16 payoutPercentage;
@@ -25,15 +30,29 @@ contract Listings is Initializable, OwnableUpgradeable {
         bool initialized;
     }
 
+    /**
+     * @notice Tracks each Node's listing.
+     */
     mapping(address => Listing) public listings;
 
+    /**
+     * @notice Payout percentage refers to the portion of a tickets reward
+     * that will be allocated to the Node's stakers. This global, and is
+     * currently set for all Nodes for phase two.
+     */
     uint16 public defaultPayoutPercentage;
 
     function initialize(uint16 _defaultPayoutPercentage) public initializer {
         OwnableUpgradeable.__Ownable_init();
         setDefaultPayoutPercentage(_defaultPayoutPercentage);
     }
 
+    /**
+     * @notice Set the global default payout percentage value. Only callable
+     * by the owner.
+     * @param _defaultPayoutPercentage The payout percentage as a value where the
+     * denominator is 10000.
+     */
     function setDefaultPayoutPercentage(uint16 _defaultPayoutPercentage) public onlyOwner {
         require(
             _defaultPayoutPercentage <= 10000,
@@ -42,6 +61,13 @@ contract Listings is Initializable, OwnableUpgradeable {
         defaultPayoutPercentage = _defaultPayoutPercentage;
     }
 
+    /**
+     * @notice Call this as a Node to set or update your Listing entry.
+     * @param multiAddr The libp2p multiAddr of your Node. Essential for
+     * clients to be able to establish a p2p connection.
+     * @param minDelegatedStake The minimum amount of stake in SOLO that
+     * a staker must add when calling StakingManager.addStake.
+     */
     function setListing(string memory multiAddr, uint256 minDelegatedStake) public {
         require(bytes(multiAddr).length != 0, "Multiaddr string is empty");
 
@@ -50,6 +76,11 @@ contract Listings is Initializable, OwnableUpgradeable {
         listings[msg.sender] = listing;
     }
 
+    /**
+     * @notice Retrieve the listing associated with a Node.
+     * @param account The address of the Node.
+     * @return The Node's Listing.
+     */
     function getListing(address account) public view returns (Listing memory) {
         return listings[account];
     }