Escrow Comment Recommendations

Escrow Comment Recommendations.md

Proposed directory structure:

contracts/
  escrow/
    ConditionalEscrow.sol
    Escrow.sol
    RefundEscrow.sol
  payment/
    PullPayment.sol
    SplitPayment.sol

Natspec comment improvement suggestions:

Escrow.sol

/**
 * @title Escrow
 * @dev Base escrow contract, holds funds designated for a payee until they
 * withdraw them. 
 * @dev Intended usage: This contract (and derived escrow contracts) should be a 
 * standalone contract, that only interacts with the contract that instantiated 
 * it. That way, it is guaranteed that all Ether will be handled according to 
 * the Escrow rules, and there is no need to check for payable functions or 
 * transfers in the inheritance tree. The contract that uses the escrow as its 
 * payment method should be its primary, and provide public methods redirecting 
 * to the escrow's deposit and withdraw.
 */

ConditionalEscrow.sol

/**
 * @title ConditionalEscrow
 * @dev Base abstract escrow to only allow withdrawal if a condition is met. 
 * @dev Intended usage: See Escrow.sol. Same usage guidelines apply here. 
 */

RefundEscrow.sol

/**
 * @title RefundEscrow
 * @dev Escrow that holds funds for a beneficiary, deposited from multiple
 * parties.
 * @dev Intended usage: See Escrow.sol. Same usage guidelines apply here.
 * @dev The primary account (that is, the contract that instantiates this 
 * contract) may deposit, close the deposit period, and allow for either 
 * withdrawal by the beneficiary, or refunds to the depositors. All interactions 
 * with RefundEscrow will be made through the primary contract. See the 
 * RefundableCrowdsale contract for an example of RefundEscrow’s use.
 */