Add comments / tidy up Crowdsale base class

contracts/crowdsale-refactor/Crowdsale.sol

@@ -3,15 +3,35 @@ pragma solidity ^0.4.18;
 import "../token/ERC20/ERC20.sol";
 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
+ * functionality and/or custom behavior.
+ */
 contract Crowdsale {
   using SafeMath for uint256;
 
+  // The token being sold
   ERC20 public token;
 
+  // Address where funds are collected
   address public wallet;
+
+  // How many token units a buyer gets per wei
   uint256 public rate;
+
+  // Amount of wei raised
   uint256 public weiRaised;
 
+  /**
+   * Event for token purchase logging
+   * @param purchaser who paid for the tokens
+   * @param beneficiary who got the tokens
+   * @param value weis paid for purchase
+   * @param amount amount of tokens purchased
+   */
   event TokenPurchase(address indexed purchaser, address indexed beneficiary, uint256 value, uint256 amount);
 
   function Crowdsale(uint256 _rate, address _wallet, ERC20 _token) public {
@@ -28,10 +48,21 @@ 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.
+  */
+
+  // Fallback function routes to buyTokens()
+  // *** DO NOT OVERRIDE ***
   function () external payable {
     buyTokens(msg.sender);
   }
 
+  // Low level token purchase function
+  // *** DO NOT OVERRIDE ***
   function buyTokens(address beneficiary) public payable {
 
     uint256 weiAmount = msg.value;
@@ -54,27 +85,47 @@ contract Crowdsale {
   // Internal (extensible) implementations
   // -----------------------------------------
 
+  /** 
+  * These functions conform the extensible 
+  * and modifyable surface of crowdsales. 
+  * Override the methods to add additional functionality.
+  * Consider using 'super' where appropiate to concatenate
+  * behavior.
+  */
+
+  // Validation of an incoming purchase.
+  // Use require to revert when conditions are not met.
   function _preValidatePurchase(address _beneficiary, uint256 _weiAmount) internal {
     require(_beneficiary != address(0));
     require(_weiAmount != 0);
   }
 
+  // Validation of an executed purchase.
+  // Observe state and use revert/require to undo changes.
   function _postValidatePurchase(address beneficiary, uint256 weiAmount) internal {
     // optional override
   }
 
+  // Ultimate source of tokens.
+  // Override this method to modify how the crowdsale ultimately gets and 
+  // sends its tokens.
   function _emitTokens(address _beneficiary, uint256 _tokenAmount) internal {
     token.transfer(_beneficiary, _tokenAmount);
   }
 
+  // Executed when a purchase has been validated and is ready to be executed.
+  // Might not necessarily emit/send tokens.
   function _processPurchase(address _beneficiary, uint256 _tokenAmount) internal {
     _emitTokens(_beneficiary, _tokenAmount);
   }
 
+  // Determines the relationship of ETH to amount of tokens.
+  // Not necessarily determined directly by rate.
   function _getTokenAmount(uint256 weiAmount) internal view returns (uint256) {
     return weiAmount.mul(rate);
   }
 
+  // Determines how ETH is stored/forwarded on purchases.
   function _forwardFunds() internal {
     wallet.transfer(msg.value);
   }

contracts/crowdsale-refactor/distribution/PostDeliveryCrowdsale.sol

@@ -5,7 +5,7 @@ import "../../token/ERC20/ERC20.sol";
 
 contract PostDeliveryCrowdsale is TimedCrowdsale {
 
-  mapping(address => uint256) promised;
+  mapping(address => uint256) promises;
 
   function processPurchase(address _beneficiary, uint256 _tokenAmount) internal {
     promises[_beneficiary] = promises[_beneficiary].add(_tokenAmount);
@@ -16,6 +16,6 @@ contract PostDeliveryCrowdsale is TimedCrowdsale {
     uint256 amount = promises[msg.sender];
     require(amount > 0);
     promises[msg.sender] = 0;
-    emitTokens(msg.sender, amount);
+    _emitTokens(msg.sender, amount);
   }
 }

contracts/crowdsale-refactor/validation/CappedCrowdsale.sol

@@ -19,7 +19,7 @@ contract CappedCrowdsale is TimedCrowdsale {
   }
 
   function _postValidatePurchase(address _beneficiary, uint256 _weiAmount) internal {
-    super.postValidatePurchase(_beneficiary, _weiAmount);
+    super._postValidatePurchase(_beneficiary, _weiAmount);
     require(weiRaised <= cap);
   }
 

contracts/crowdsale-refactor/validation/TimedCrowdsale.sol

@@ -20,6 +20,7 @@ contract TimedCrowdsale is Crowdsale {
   }
 
   function _preValidatePurchase(address _beneficiary, uint256 _weiAmount) internal {
+    super._preValidatePurchase(_beneficiary, _weiAmount);
     require(now >= startTime && now <= endTime);
   }
 }

contracts/crowdsale-refactor/validation/UserCappedCrowdsale.sol

@@ -21,7 +21,7 @@ contract UserCappedCrowdsale is Crowdsale, Ownable {
   }
 
   function _postValidatePurchase(address _beneficiary, uint256 _weiAmount) internal {
-    super.postValidatePurchase(_beneficiary, _weiAmount);
+    super._postValidatePurchase(_beneficiary, _weiAmount);
     contributions[_beneficiary] = contributions[_beneficiary].add(_weiAmount);
     require(contributions[_beneficiary] <= caps[_beneficiary]);
   }

contracts/crowdsale-refactor/validation/WhitelistedCrowdsale.sol

@@ -20,7 +20,7 @@ contract WhitelistedCrowdsale is Crowdsale, Ownable {
   }
 
   function _preValidatePurchase(address _beneficiary, uint256 _weiAmount) internal {
-    super.preValidatePurchase(_beneficiary, _weiAmount);
+    super._preValidatePurchase(_beneficiary, _weiAmount);
     require(isWhitelisted(_beneficiary));
   }
 }