Add more extensive documentation to PaymentSplitter (#1713)

* Update PaymentSplitter.sol

* add back private function docs

* add non-zero address requirement

* add comprehensive contract-level docs

* use capital E for Ether

contracts/payment/PaymentSplitter.sol

@@ -4,8 +4,16 @@ import "../math/SafeMath.sol";
 
 /**
  * @title PaymentSplitter
- * @dev This contract can be used when payments need to be received by a group
- * of people and split proportionately to some number of shares they own.
+ * @dev This contract allows to split Ether payments among a group of accounts. The sender does not need to be aware
+ * that the Ether will be split in this way, since it is handled purely by the contract.
+ *
+ * The split can be in equal parts or in any other arbitrary proportion. The way this is specified is by assigning each
+ * account to a number of shares. Of all the Ether that this contract receives, each account will then be able to claim
+ * an amount proportional to the percentage of total shares they were assigned.
+ *
+ * `PaymentSplitter` follows a _pull payment_ model. This means that payments are not automatically forwarded to the
+ * accounts but kept in this contract, and the actual transfer is triggered as a separate step by calling the `release`
+ * function.
  */
 contract PaymentSplitter {
     using SafeMath for uint256;
@@ -22,7 +30,11 @@ contract PaymentSplitter {
     address[] private _payees;
 
     /**
-     * @dev Constructor.
+     * @dev Creates an instance of `PaymentSplitter` where each account in `payees` is assigned the number of shares at
+     * the matching position in the `shares` array.
+     *
+     * All addresses in `payees` must be non-zero. Both arrays must have the same non-zero length, and there must be no
+     * duplicates in `payees`.
      */
     constructor (address[] memory payees, uint256[] memory shares) public payable {
         require(payees.length == shares.length);
@@ -34,50 +46,56 @@ contract PaymentSplitter {
     }
 
     /**
-     * @dev Payable fallback.
+     * @dev The Ether received will be logged with `PaymentReceived` events. Note that these events are not fully
+     * reliable: it's possible for a contract to receive Ether without triggering this function. This only affects the
+     * reliability of the events, and not the actual splitting of Ether.
+     *
+     * To learn more about this see the Solidity documentation for [fallback functions].
+     *
+     * [fallback functions]: https://solidity.readthedocs.io/en/latest/contracts.html#fallback-function
      */
     function () external payable {
         emit PaymentReceived(msg.sender, msg.value);
     }
 
     /**
-     * @return the total shares of the contract.
+     * @dev Getter for the total shares held by payees.
      */
     function totalShares() public view returns (uint256) {
         return _totalShares;
     }
 
     /**
-     * @return the total amount already released.
+     * @dev Getter for the total amount of Ether already released.
      */
     function totalReleased() public view returns (uint256) {
         return _totalReleased;
     }
 
     /**
-     * @return the shares of an account.
+     * @dev Getter for the amount of shares held by an account.
      */
     function shares(address account) public view returns (uint256) {
         return _shares[account];
     }
 
     /**
-     * @return the amount already released to an account.
+     * @dev Getter for the amount of Ether already released to a payee.
      */
     function released(address account) public view returns (uint256) {
         return _released[account];
     }
 
     /**
-     * @return the address of a payee.
+     * @dev Getter for the address of the payee number `index`.
      */
     function payee(uint256 index) public view returns (address) {
         return _payees[index];
     }
 
     /**
-     * @dev Release one of the payee's proportional payment.
-     * @param account Whose payments will be released.
+     * @dev Triggers a transfer to `account` of the amount of Ether they are owed, according to their percentage of the
+     * total shares and their previous withdrawals.
      */
     function release(address payable account) public {
         require(_shares[account] > 0);