expanded docs throughout, fixed minor issues

OpenZeppelin · maraoz · Feb 20, 2018 · Feb 4, 2018 · Feb 5, 2018 · Feb 5, 2018
commit e716a22f5f535728146bdd3229cecf0c97a3b37e
@@ -7,9 +7,15 @@ import "../math/SafeMath.sol";
  * @title Crowdsale
  * @dev Crowdsale is a base contract for managing a token crowdsale,
  * allowing investors to purchase tokens with ether. This contract implements
- * such functionality in it's most fundamental form and can be extended to provide additional
+ * such functionality in its most fundamental form and can be extended to provide additional
  * functionality and/or custom behavior.
+ * The external interface represents the basic interface for purchasing tokens, and conform
+ * the base architecture for crowdsales. They are *not* intended to be modified / overriden.
+ * The internal interface conforms the extensible and modifiable surface of crowdsales. Override 
+ * the methods to add functionality. Consider using 'super' where appropiate to concatenate
+ * behavior.
  */
+
 contract Crowdsale {
   using SafeMath for uint256;
 
@@ -53,13 +59,6 @@ contract Crowdsale {
   // Crowdsale external interface
   // -----------------------------------------
 
-  /**
-  * These functions represent the basic
-  * interface for purchasing tokens, conform
-  * the base architecture for crowdsales,
-  * and are not intended to be modified / overriden.
-  */
-
   /**
    * @dev fallback function ***DO NOT OVERRIDE***
    */
@@ -92,17 +91,9 @@ contract Crowdsale {
   }
 
   // -----------------------------------------
-  // Internal (extensible) implementations
+  // Internal interface (extensible)
   // -----------------------------------------
 
-  /**
-  * These functions conform the extensible
-  * and modifiable surface of crowdsales.
-  * Override the methods to add additional functionality.
-  * Consider using 'super' where appropiate to concatenate
-  * behavior.
-  */
-
   /**
    * @dev Validation of an incoming purchase. Use require statemens to revert state when conditions are not met. Use super to concatenate validations.
    * @param _beneficiary Address performing the token purchase

@@ -6,19 +6,24 @@ import "../../math/SafeMath.sol";
 
 /**
  * @title PostDeliveryCrowdsale
- * @dev Crowdsale that locks funds from withdrawal until it ends
+ * @dev Crowdsale that locks tokens from withdrawal until it ends.
  */
 contract PostDeliveryCrowdsale is TimedCrowdsale {
   using SafeMath for uint256;
 
   mapping(address => uint256) public promises;
 
+  /**
+   * @dev Overrides parent by storing balances instead of issuing tokens right away.
+   * @param _beneficiary Token purchaser
+   * @param _tokenAmount Amount of tokens purchased
+   */
   function _processPurchase(address _beneficiary, uint256 _tokenAmount) internal {
     promises[_beneficiary] = promises[_beneficiary].add(_tokenAmount);
   }
 
   /**
-   * @dev Withdraw tokens only after crowdsale ends
+   * @dev Withdraw tokens only after crowdsale ends.
    */
   function withdrawTokens() public {
     require(hasExpired());

@@ -63,7 +63,7 @@ contract RefundableCrowdsale is FinalizableCrowdsale {
   }
 
   /**
-   * @dev Overrides Crowdsale fund forwarding. In addition to sending the funds, we call the RefundVault deposit function
+   * @dev Overrides Crowdsale fund forwarding, sending funds to vault.
    */
   function _forwardFunds() internal {
     vault.deposit.value(msg.value)(msg.sender);

@@ -4,6 +4,11 @@ import "../Crowdsale.sol";
 import "../../token/ERC20/ERC20.sol";
 import "../../math/SafeMath.sol";
 
+
+/**
+ * @title AllowanceCrowdsale
+ * @dev Extension of Crowdsale where tokens are held by a wallet, which approves an allowance to the crowdsale.
+ */
 contract AllowanceCrowdsale is Crowdsale {
   using SafeMath for uint256;
 
@@ -24,6 +29,11 @@ contract AllowanceCrowdsale is Crowdsale {
     return token.allowance(tokenWallet, this);
   }
 
+  /**
+   * @dev Overrides parent behavior by transferring tokens from wallet.
+   * @param _beneficiary Token purchaser
+   * @param _tokenAmount Amount of tokens purchased
+   */
   function _emitTokens(address _beneficiary, uint256 _tokenAmount) internal {
     token.transferFrom(tokenWallet, _beneficiary, _tokenAmount);
   }

@@ -3,8 +3,19 @@ pragma solidity ^0.4.18;
 import "../Crowdsale.sol";
 import "../../token/ERC20/MintableToken.sol";
 
+
+/**
+ * @title MintedCrowdsale
+ * @dev Extension of Crowdsale contract whose tokens are minted in each purchase.
+ * Token ownership should be transferred to MintedCrowdsale for minting. 
+ */
 contract MintedCrowdsale is Crowdsale {
 
+  /**
+  * @dev Overrides emission by minting tokens upon purchase.
+  * @param _beneficiary Token purchaser
+  * @param _tokenAmount Number of tokens to be minted
+  */
   function _emitTokens(address _beneficiary, uint256 _tokenAmount) internal {
     require(MintableToken(token).mint(_beneficiary, _tokenAmount));
   }

@@ -3,7 +3,12 @@ pragma solidity ^0.4.18;
 import "../validation/TimedCrowdsale.sol";
 import "../../math/SafeMath.sol";
 
-
+/**
+ * @title IncreasingPriceCrowdsale
+ * @dev Extension of Crowdsale contract that increases the price of tokens linearly in time. 
+ * Note that what should be provided to the constructor is the initial and final _rates_, that is,
+ * the amount of tokens per ETH contributed. Thus, the initial rate must be greater than the final rate.
+ */
 contract IncreasingPriceCrowdsale is TimedCrowdsale {
   using SafeMath for uint256;
 
@@ -22,15 +27,22 @@ contract IncreasingPriceCrowdsale is TimedCrowdsale {
   }
 
   /**
+   * @dev Returns the rate of tokens per ETH at the present time. 
+   * Note that, as price _increases_ with time, the rate _decreases_. 
    * @return The number of tokens a buyer gets per wei at a given time
    */
   function getCurrentRate() public view returns (uint256) {
-    uint256 elapsedTime = now - startTime;
-    uint256 timeRange = endTime - startTime;
-    uint256 rateRange = initialRate - finalRate;
+    uint256 elapsedTime = now.sub(startTime);
+    uint256 timeRange = endTime.sub(startTime);
+    uint256 rateRange = initialRate.sub(finalRate);
     return initialRate.sub(elapsedTime.mul(rateRange).div(timeRange));
   }
 
+  /**
+   * @dev Overrides parent method taking into account variable rate.
+   * @param _weiAmount The value in wei to be converted into tokens
+   * @return The number of tokens _weiAmount wei will buy at present time
+   */
   function _getTokenAmount(uint256 _weiAmount) internal view returns (uint256) {
     uint256 currentRate = getCurrentRate();
     return currentRate.mul(_weiAmount);

@@ -3,8 +3,10 @@ pragma solidity ^0.4.18;
 import "../../math/SafeMath.sol";
 import "../Crowdsale.sol";
 
+
 /**
- * @dev Crowdsale with a limit for total contributions
+ * @title CappedCrowdsale
+ * @dev Crowdsale with a limit for total contributions.
  */
 contract CappedCrowdsale is Crowdsale {
   using SafeMath for uint256;
@@ -26,6 +28,11 @@ contract CappedCrowdsale is Crowdsale {
     return weiRaised >= cap;
   }
 
+  /**
+   * @dev Extend parent behavior requiring to not exceed the cap.
+   * @param _beneficiary Token purchaser
+   * @param _weiAmount Amount of wei contributed
+   */
   function _postValidatePurchase(address _beneficiary, uint256 _weiAmount) internal {
     super._postValidatePurchase(_beneficiary, _weiAmount);
     require(weiRaised <= cap);

@@ -4,8 +4,10 @@ import "../../math/SafeMath.sol";
 import "../Crowdsale.sol";
 import "../../ownership/Ownable.sol";
 
+
 /**
- * @dev Crowdsale with per-user caps
+ * @title IndividuallyCappedCrowdsale
+ * @dev Crowdsale with per-user caps.
  */
 contract IndividuallyCappedCrowdsale is Crowdsale, Ownable {
   using SafeMath for uint256;
@@ -37,11 +39,21 @@ contract IndividuallyCappedCrowdsale is Crowdsale, Ownable {
     return contributions[_beneficiary];
   }
 
+  /**
+   * @dev Extend parent behavior requiring to not exceed the individual cap.
+   * @param _beneficiary Token purchaser
+   * @param _weiAmount Amount of wei contributed
+   */
   function _postValidatePurchase(address _beneficiary, uint256 _weiAmount) internal {
     super._postValidatePurchase(_beneficiary, _weiAmount);
     require(contributions[_beneficiary] <= caps[_beneficiary]);
   }
 
+  /**
+   * @dev Extend parent behavior to update user contributions
+   * @param _beneficiary Token purchaser
+   * @param _weiAmount Amount of wei contributed
+   */
   function _updatePurchasingState(address _beneficiary, uint256 _weiAmount) internal {
     super._updatePurchasingState(_beneficiary, _weiAmount);
     contributions[_beneficiary] = contributions[_beneficiary].add(_weiAmount);

@@ -3,8 +3,10 @@ pragma solidity ^0.4.18;
 import "../../math/SafeMath.sol";
 import "../Crowdsale.sol";
 
+
 /**
- * @dev Crowdsale accepting contributions only within a time frame
+ * @title TimedCrowdsale
+ * @dev Crowdsale accepting contributions only within a time frame.
  */
 contract TimedCrowdsale is Crowdsale {
   using SafeMath for uint256;
@@ -30,7 +32,12 @@ contract TimedCrowdsale is Crowdsale {
   function hasExpired() public view returns (bool) {
     return now > endTime;
   }
-
+
+  /**
+   * @dev Extend parent behavior requiring to be within contributing period
+   * @param _beneficiary Token purchaser
+   * @param _weiAmount Amount of wei contributed
+   */
   function _preValidatePurchase(address _beneficiary, uint256 _weiAmount) internal {
     super._preValidatePurchase(_beneficiary, _weiAmount);
     require(now >= startTime && now <= endTime);

@@ -3,8 +3,10 @@ pragma solidity ^ 0.4.18;
 import "../Crowdsale.sol";
 import "../../ownership/Ownable.sol";
 
+
 /**
- * @dev Crowdsale in which only whitelisted users can contribute
+ * @title WhitelistedCrowdsale
+ * @dev Crowdsale in which only whitelisted users can contribute.
  */
 contract WhitelistedCrowdsale is Crowdsale, Ownable {
 
@@ -32,6 +34,11 @@ contract WhitelistedCrowdsale is Crowdsale, Ownable {
     return whitelist[_beneficiary];
   }
 
+  /**
+   * @dev Extend parent behavior requiring beneficiary to be in whitelist.
+   * @param _beneficiary Token beneficiary
+   * @param _weiAmount Amount of wei contributed
+   */
   function _preValidatePurchase(address _beneficiary, uint256 _weiAmount) internal {
     super._preValidatePurchase(_beneficiary, _weiAmount);
     require(isWhitelisted(_beneficiary));