Moved Escrows into an escrow subdirectory, improved docs. (#1430)

* Moved Escrows into an escrow subdirectory, improved docs.

* Fixed escrow mock.

* Fixed some more imports.

(cherry picked from commit f3df2dab3d)

contracts/crowdsale/distribution/RefundableCrowdsale.sol

@@ -2,7 +2,7 @@ pragma solidity ^0.4.24;
 
 import "../../math/SafeMath.sol";
 import "./FinalizableCrowdsale.sol";
-import "../../payment/RefundEscrow.sol";
+import "../../payment/escrow/RefundEscrow.sol";
 
 /**
  * @title RefundableCrowdsale

contracts/mocks/ConditionalEscrowMock.sol

@@ -1,6 +1,6 @@
 pragma solidity ^0.4.24;
 
-import "../payment/ConditionalEscrow.sol";
+import "../payment/escrow/ConditionalEscrow.sol";
 
 // mock class using ConditionalEscrow
 contract ConditionalEscrowMock is ConditionalEscrow {

contracts/payment/PullPayment.sol

@@ -1,6 +1,6 @@
 pragma solidity ^0.4.24;
 
-import "./Escrow.sol";
+import "./escrow/Escrow.sol";
 
 /**
  * @title PullPayment

contracts/payment/escrow/ConditionalEscrow.sol

@@ -5,6 +5,7 @@ import "./Escrow.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.
  */
 contract ConditionalEscrow is Escrow {
   /**

contracts/payment/escrow/Escrow.sol

@@ -1,14 +1,19 @@
 pragma solidity ^0.4.24;
 
-import "../math/SafeMath.sol";
+import "../../math/SafeMath.sol";
-import "../ownership/Secondary.sol";
+import "../../ownership/Secondary.sol";
 
-/**
+ /**
  * @title Escrow
- * @dev Base escrow contract, holds funds destinated to a payee until they
+ * @dev Base escrow contract, holds funds designated for a payee until they
- * withdraw them. The contract that uses the escrow as its payment method
+ * withdraw them.
- * should be its primary, and provide public methods redirecting to the escrow's
+ * @dev Intended usage: This contract (and derived escrow contracts) should be a
- * deposit and withdraw.
+ * 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.
  */
 contract Escrow is Secondary {
   using SafeMath for uint256;

contracts/payment/escrow/RefundEscrow.sol

@@ -4,9 +4,14 @@ import "./ConditionalEscrow.sol";
 
 /**
  * @title RefundEscrow
- * @dev Escrow that holds funds for a beneficiary, deposited from multiple parties.
+ * @dev Escrow that holds funds for a beneficiary, deposited from multiple
- * The primary account may close the deposit period, and allow for either withdrawal
+ * parties.
- * by the beneficiary, or refunds to the depositors.
+ * @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.
  */
 contract RefundEscrow is ConditionalEscrow {
   enum State { Active, Refunding, Closed }

test/payment/escrow/ConditionalEscrow.test.js

@@ -1,7 +1,7 @@
 const { shouldBehaveLikeEscrow } = require('./Escrow.behavior');
 
-const shouldFail = require('../helpers/shouldFail');
+const shouldFail = require('../../helpers/shouldFail');
-const { ether } = require('../helpers/ether');
+const { ether } = require('../../helpers/ether');
 
 const BigNumber = web3.BigNumber;
 

test/payment/escrow/Escrow.behavior.js

@@ -1,7 +1,7 @@
-const expectEvent = require('../helpers/expectEvent');
+const expectEvent = require('../../helpers/expectEvent');
-const shouldFail = require('../helpers/shouldFail');
+const shouldFail = require('../../helpers/shouldFail');
-const { ethGetBalance } = require('../helpers/web3');
+const { ethGetBalance } = require('../../helpers/web3');
-const { ether } = require('../helpers/ether');
+const { ether } = require('../../helpers/ether');
 
 const BigNumber = web3.BigNumber;
 

test/payment/escrow/RefundEscrow.test.js

@@ -1,8 +1,8 @@
-const shouldFail = require('../helpers/shouldFail');
+const shouldFail = require('../../helpers/shouldFail');
-const expectEvent = require('../helpers/expectEvent');
+const expectEvent = require('../../helpers/expectEvent');
-const { ethGetBalance } = require('../helpers/web3');
+const { ethGetBalance } = require('../../helpers/web3');
-const { ether } = require('../helpers/ether');
+const { ether } = require('../../helpers/ether');
-const { ZERO_ADDRESS } = require('../helpers/constants');
+const { ZERO_ADDRESS } = require('../../helpers/constants');
 
 const BigNumber = web3.BigNumber;