merge api docs changes

Squashed commit of the following:

commit 06243c3e8e86074ff8e9e3f22b7829a2c315d707
Merge: 991882ec 99373558
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 18:15:37 2019 -0300

    Merge branch 'api-docs' into api-docs-merge

commit 991882eca5bb8a3391995154bfb9d53d8a69cb4f
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 18:08:02 2019 -0300

    manually apply docs changes and renamings

commit fa1f6e97dd67a76c3cd828d0a5e19b4ac6c37acb
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 17:36:03 2019 -0300

    move functions to new order

commit 99373558e3af4905d29bc6f3f542ba93d28a24ab
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 16:23:40 2019 -0300

    add missing docs links

commit d180d6c36a6f5460e85473ee5a18992d1449a6ff
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 16:14:12 2019 -0300

    update solidity-docgen dependency

    fixes uri encoded links

commit faab0e50da91cd2f0a409e3ad32e2db127ad319a
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 16:05:03 2019 -0300

    update openzeppelin-docsite and solidity-docgen dependencies

    add visibility specifiers

commit ef305268bb2735e488e35d16819a4b432b3a35e3
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Thu May 23 15:36:45 2019 -0300

    Fix guide links.

commit 339b20dbfa2d5f6ea02e63c2f3fdcba0fe879c3c
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Thu May 23 13:37:51 2019 -0300

    Fix typos.

commit 6c7b97460578b9eea90b53c280454e361f8f0052
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 15:26:29 2019 -0300

    fix utilities guide links

commit 0e7692a8fd8516a11becc4121d77d792439600b1
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 15:23:19 2019 -0300

    update solidity-docgen dependency

commit ebb8a8651516ece21736c6c3b2577eb1b3487651
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 15:15:01 2019 -0300

    fix utilities guide links

commit 5ec47d62785e1d6e5f8e91edca58f2dc7f87d7a3
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 15:14:49 2019 -0300

    fix escrow docs ordering

commit cdcdc909b16f219a9a3272036b6a8f21e34b48ef
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 13:35:07 2019 -0300

    add wip notice

commit 987e2951ae93211c8c70c8288e30573555c57830
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 13:09:35 2019 -0300

    update openzeppelin-docsite dependency

    fixes links to old versions

commit b00d22c0affac2e2108df8b773dfa1706afcb44e
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 23 13:09:28 2019 -0300

    fix guide links

commit f112a9400c5e5ad495c8e0fdb972e26987b34244
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 20:42:37 2019 -0300

    update docsite

commit 68aacdd56a29e35a84f6732f9293612bbcaf7520
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Wed May 22 20:00:39 2019 -0300

    ERC20Capped

commit 4edce78bab2c6d140f3ea3f33db71e92ca4d8aaf
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Wed May 22 19:52:30 2019 -0300

    Unnecessary polish on token docs.

commit 2a4c91cf49c2736dc09c1c03cf383911def1a1b2
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 19:20:05 2019 -0300

    rename guides

commit 61dd818ea76d4c170c4ab175c6be0d6067d21a29
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Wed May 22 17:04:09 2019 -0300

    ERC1820 docs.

commit 77b5f0353123b76358dc6d86bdc646c86c9b0bea
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Wed May 22 16:17:34 2019 -0300

    Introspection and ERC165.

commit 76641a253b3b70279802c5134dd107532eea4b2c
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 17:59:53 2019 -0300

    update docgen

commit 7be98bc3fbd3566231f943f01b9acb58567d755b
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 17:23:50 2019 -0300

    update solidity-docgen

commit f7268e6e010f8ef9ac83df241a803f91efc08c0c
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 16:58:31 2019 -0300

    update docgen

commit 2a8c7a378e8962a5baeb334b2492815f05075f98
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Wed May 22 14:36:35 2019 -0300

    Util docs.

commit 327ae8ff45a1a523c7591bf4996c4a9b52d7ec7a
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 13:08:50 2019 -0300

    add missing drafts

commit 5e7f71335ac8423c0e363ae8c7ad9b2977f202f8
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 12:47:41 2019 -0300

    tweak ierc20 docs

commit cd0e86a0b712f74ffd406e072d4b1fbf4dd2c176
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 12:46:45 2019 -0300

    add some erc721 docs

commit e081184159417f71da14bc0fc110b7b11e29d75d
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 12:41:46 2019 -0300

    update docsite

commit 0beb75784022419d47123c2a9fe7a5f1eb87f9b2
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 12:22:27 2019 -0300

    correct drafts structure

commit 2e94b287c7cead7a6c0603205670566461c31abb
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 11:56:25 2019 -0300

    fix docsite-start script

commit 0fa4160484309d0851584fe57c0d81a3600977db
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 11:47:44 2019 -0300

    improve docsite start script (automatically watch docgen)

commit 9d571897cc03bee92035964cf7a2cfeda1e2f690
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 22 11:30:37 2019 -0300

    update solidity-docgen

commit 82980f5aefbdfb8a9815a3b7b0e88e970b65dd5d
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue May 21 19:15:13 2019 -0300

    edit docs for Secondary

commit 00d7a005b0530bee730b77a1b69a95f1b4ffe315
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue May 21 19:15:13 2019 -0300

    edit docs for ownable

commit b0c4c2bdf83eca5d4a71792daac603236733d46e
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue May 21 18:27:13 2019 -0300

    change title of Math section

commit deb788583f191780e55b7f673520eaf13a5c7e23
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue May 21 18:26:59 2019 -0300

    capitalization

commit f2bcf85d343ea4a0739fe22a77b1e22c2296ddea
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue May 21 18:26:06 2019 -0300

    edit docs for Pausable

commit 73ba0cf43dbb44c39c1bf2ee63ef9fe558faa919
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Sat May 18 19:08:06 2019 -0300

    Crypto docs.

commit 9d6fc6223f51cf2321b2e3217c512579654c3917
Merge: 7e21f8f7 9f1cec12
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Fri May 17 17:23:15 2019 -0300

    Merge branch 'api-docs-777' into api-docs

commit 9f1cec12e3351fb1b5fc0b59f5ded39928064a56
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Fri May 17 17:22:54 2019 -0300

    ERC777 done.

commit 7e21f8f7b6982d2f92df302cdf6ec62522d8ffff
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri May 17 16:39:47 2019 -0300

    add math docs

commit f18d1f17023b6e5b42ae04fc38aa1170e6863864
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Thu May 16 20:01:46 2019 -0300

    First draft of ERC777 docs.

commit 985c5d305329fd9d400120d86dce5c386e19cd50
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Thu May 16 19:14:32 2019 -0300

    Final draft for IERC777.

commit bf53f133d987b67f938a329e6d659ba3483aab0b
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 16 19:13:37 2019 -0300

    more work on ERC20 api docs

commit b7c250b7cb4669448cfab5535c4ff70b94a15635
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Thu May 16 17:08:47 2019 -0300

    Fix typo.

commit 197bbfbfc67a09607ead492b834879c62b3d905a
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Thu May 16 17:05:14 2019 -0300

    Initial draft of IERC777.

commit 7dc3b55161c860437a8f13a2ce5808b1c3dd70a2
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu May 16 11:58:32 2019 -0300

    add payment docs structure

commit da16fc4480243181e58c3440e977e76a91a1839a
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date:   Thu May 16 16:05:33 2019 -0300

    Initial ERC777 docstrings.

commit 9f6a7e35bd2f045e6063ca2f93c67b792c0ef47c
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed May 15 22:13:17 2019 -0300

    partial pass through ERC20 docs

.solhint.json

@@ -2,7 +2,7 @@
   "extends": "default",
   "rules": {
     "indent": ["error", 4],
-
+    "func-order": false,
     "bracket-align": false,
     "compiler-fixed": false,
     "no-simple-event-func-name": false,

contracts/access/README.md

@@ -5,3 +5,5 @@ sections:
       - Roles
   - subdirectory: roles
 ---
+
+> This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/crowdsale/README.md

@@ -9,3 +9,5 @@ sections:
   - subdirectory: validation
   - subdirectory: distribution
 ---
+
+> This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/crowdsale/distribution/RefundableCrowdsale.sol

@@ -6,10 +6,10 @@ import "../../payment/escrow/RefundEscrow.sol";
 
 /**
  * @title RefundableCrowdsale
- * @dev Extension of FinalizableCrowdsale contract that adds a funding goal, and the possibility of users
+ * @dev Extension of `FinalizableCrowdsale` contract that adds a funding goal, and the possibility of users
  * getting a refund if goal is not met.
  *
- * Deprecated, use RefundablePostDeliveryCrowdsale instead. Note that if you allow tokens to be traded before the goal
+ * Deprecated, use `RefundablePostDeliveryCrowdsale` instead. Note that if you allow tokens to be traded before the goal
  * is met, then an attack is possible in which the attacker purchases tokens from the crowdsale and when they sees that
  * the goal is unlikely to be met, they sell their tokens (possibly at a discount). The attacker will be refunded when
  * the crowdsale is finalized, and the users that purchased from them will be left with worthless tokens.

contracts/cryptography/ECDSA.sol

@@ -1,17 +1,29 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title Elliptic curve signature operations
- * @dev Based on https://gist.github.com/axic/5b33912c6f61ae6fd96d6c4a47afde6d
- * TODO Remove this library once solidity supports passing a signature to ecrecover.
- * See https://github.com/ethereum/solidity/issues/864
+ * @dev Elliptic Curve Digital Signature Algorithm (ECDSA) operations.
+ *
+ * These functions can be used to verify that a message was signed by the holder
+ * of the private keys of a given address.
  */
-
 library ECDSA {
     /**
-     * @dev Recover signer address from a message by using their signature.
-     * @param hash bytes32 message, the hash is the signed message. What is recovered is the signer address.
-     * @param signature bytes signature, the signature is generated using web3.eth.sign()
+     * @dev Returns the address that signed a hashed message (`hash`) with
+     * `signature`. This address can then be used for verification purposes.
+     *
+     * The `ecrecover` EVM opcode allows for malleable (non-unique) signatures:
+     * this function rejects them by requiring the `s` value to be in the lower
+     * half order, and the `v` value to be either 27 or 28.
+     *
+     * (.note) This call _does not revert_ if the signature is invalid, or
+     * if the signer is otherwise unable to be retrieved. In those scenarios,
+     * the zero address is returned.
+     *
+     * (.warning) `hash` _must_ be the result of a hash operation for the
+     * verification to be secure: it is possible to craft signatures that
+     * recover to arbitrary addresses for non-hashed data. A safe way to ensure
+     * this is by receiving a hash of the original message (which may otherwise)
+     * be too long), and then calling `toEthSignedMessageHash` on it.
      */
     function recover(bytes32 hash, bytes memory signature) internal pure returns (address) {
         // Check the signature length
@@ -55,9 +67,12 @@ library ECDSA {
     }
 
     /**
-     * toEthSignedMessageHash
-     * @dev Prefix a bytes32 value with "\x19Ethereum Signed Message:"
-     * and hash the result.
+     * @dev Returns an Ethereum Signed Message, created from a `hash`. This
+     * replicates the behavior of the
+     * [`eth_sign`](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_sign)
+     * JSON-RPC method.
+     *
+     * See `recover`.
      */
     function toEthSignedMessageHash(bytes32 hash) internal pure returns (bytes32) {
         // 32 is the length in bytes of hash,

contracts/cryptography/MerkleProof.sol

@@ -1,17 +1,14 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title MerkleProof
- * @dev Merkle proof verification based on
- * https://github.com/ameensol/merkle-tree-solidity/blob/master/src/MerkleProof.sol
+ * @dev These functions deal with verification of Merkle trees (hash trees),
  */
 library MerkleProof {
     /**
-     * @dev Verifies a Merkle proof proving the existence of a leaf in a Merkle tree. Assumes that each pair of leaves
-     * and each pair of pre-images are sorted.
-     * @param proof Merkle proof containing sibling hashes on the branch from the leaf to the root of the Merkle tree
-     * @param root Merkle root
-     * @param leaf Leaf of Merkle tree
+     * @dev Returns true if a `leaf` can be proved to be a part of a Merkle tree
+     * defined by `root`. For this, a `proof` must be provided, containing
+     * sibling hashes on the branch from the leaf to the root of the tree. Each
+     * pair of leaves and each pair of pre-images are assumed to be sorted.
      */
     function verify(bytes32[] memory proof, bytes32 root, bytes32 leaf) internal pure returns (bool) {
         bytes32 computedHash = leaf;

contracts/cryptography/README.md

@@ -0,0 +1,9 @@
+---
+sections:
+  - title: Libraries
+    contracts:
+      - ECDSA
+      - MerkleProof
+---
+
+This collection of libraries provides simple and safe ways to use different cryptographic primitives.

contracts/drafts/README.md

@@ -0,0 +1,16 @@
+---
+sections:
+  - title: ERC 20
+    contracts:
+    - ERC20Migrator
+    - ERC20Snapshot
+    - TokenVesting
+  - title: Miscellenous
+    contracts:
+    - Counters
+    - SignatureBouncer
+    - SignedSafeMath
+  - subdirectory: ERC1046
+---
+
+> This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/introspection/ERC165.sol

@@ -3,9 +3,10 @@ pragma solidity ^0.5.0;
 import "./IERC165.sol";
 
 /**
- * @title ERC165
- * @author Matt Condon (@shrugs)
- * @dev Implements ERC165 using a lookup table.
+ * @dev Implementation of the `IERC165` interface.
+ *
+ * Contracts may inherit from this and call `_registerInterface` to declare
+ * their support of an interface.
  */
 contract ERC165 is IERC165 {
     /*
@@ -18,23 +19,31 @@ contract ERC165 is IERC165 {
      */
     mapping(bytes4 => bool) private _supportedInterfaces;
 
-    /**
-     * @dev A contract implementing SupportsInterfaceWithLookup
-     * implements ERC165 itself.
-     */
     constructor () internal {
+        // Derived contracts need only register support for their own interfaces,
+        // we register support for ERC165 itself here
         _registerInterface(_INTERFACE_ID_ERC165);
     }
 
     /**
-     * @dev Implement supportsInterface(bytes4) using a lookup table.
+     * @dev See `IERC165.supportsInterface`.
+     *
+     * Time complexity O(1), guaranteed to always use less than 30 000 gas.
      */
     function supportsInterface(bytes4 interfaceId) external view returns (bool) {
         return _supportedInterfaces[interfaceId];
     }
 
     /**
-     * @dev Internal method for registering an interface.
+     * @dev Registers the contract as an implementer of the interface defined by
+     * `interfaceId`. Support of the actual ERC165 interface is automatic and
+     * registering its interface id is not required.
+     *
+     * See `IERC165.supportsInterface`.
+     *
+     * Requirements:
+     *
+     * - `interfaceId` cannot be the ERC165 invalid interface (`0xffffffff`).
      */
     function _registerInterface(bytes4 interfaceId) internal {
         require(interfaceId != 0xffffffff, "ERC165: invalid interface id");

contracts/introspection/ERC165Checker.sol

@@ -1,9 +1,11 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title ERC165Checker
- * @dev Use `using ERC165Checker for address`; to include this library
- * https://eips.ethereum.org/EIPS/eip-165
+ * @dev Library used to query support of an interface declared via `IERC165`.
+ *
+ * Note that these functions return the actual result of the query: they do not
+ * `revert` if an interface is not supported. It is up to the caller to decide
+ * what to do in these cases.
  */
 library ERC165Checker {
     // As per the EIP-165 spec, no interface should ever match 0xffffffff
@@ -15,9 +17,7 @@ library ERC165Checker {
     bytes4 private constant _INTERFACE_ID_ERC165 = 0x01ffc9a7;
 
     /**
-     * @notice Query if a contract supports ERC165
-     * @param account The address of the contract to query for support of ERC165
-     * @return true if the contract at account implements ERC165
+     * @dev Returns true if `account` supports the `IERC165` interface,
      */
     function _supportsERC165(address account) internal view returns (bool) {
         // Any contract that implements ERC165 must explicitly indicate support of
@@ -27,12 +27,10 @@ library ERC165Checker {
     }
 
     /**
-     * @notice Query if a contract implements an interface, also checks support of ERC165
-     * @param account The address of the contract to query for support of an interface
-     * @param interfaceId The interface identifier, as specified in ERC-165
-     * @return true if the contract at account indicates support of the interface with
-     * identifier interfaceId, false otherwise
-     * @dev Interface identification is specified in ERC-165.
+     * @dev Returns true if `account` supports the interface defined by
+     * `interfaceId`. Support for `IERC165` itself is queried automatically.
+     *
+     * See `IERC165.supportsInterface`.
      */
     function _supportsInterface(address account, bytes4 interfaceId) internal view returns (bool) {
         // query support of both ERC165 as per the spec and support of _interfaceId
@@ -41,14 +39,15 @@ library ERC165Checker {
     }
 
     /**
-     * @notice Query if a contract implements interfaces, also checks support of ERC165
-     * @param account The address of the contract to query for support of an interface
-     * @param interfaceIds A list of interface identifiers, as specified in ERC-165
-     * @return true if the contract at account indicates support all interfaces in the
-     * interfaceIds list, false otherwise
-     * @dev Interface identification is specified in ERC-165.
+     * @dev Returns true if `account` supports all the interfaces defined in
+     * `interfaceIds`. Support for `IERC165` itself is queried automatically.
+     *
+     * Batch-querying can lead to gas savings by skipping repeated checks for
+     * `IERC165` support.
+     *
+     * See `IERC165.supportsInterface`.
      */
-    function _supportsAllInterfaces(address account, bytes4[] memory interfaceIds) internal view returns (bool) {
+     function _supportsAllInterfaces(address account, bytes4[] memory interfaceIds) internal view returns (bool) {
         // query support of ERC165 itself
         if (!_supportsERC165(account)) {
             return false;

contracts/introspection/ERC1820Implementer.sol

@@ -3,21 +3,32 @@ pragma solidity ^0.5.0;
 import "./IERC1820Implementer.sol";
 
 /**
- * @dev ERC1820Implementer allows your contract to implement an interface for another account in the sense of ERC1820.
- * That account or one of its ERC1820 managers can register the implementer in the ERC1820 registry, but the registry
- * will first check with the implementer if it agrees to it, and only allow it if it does. Using the internal
- * function _registerInterfaceForAddress provided by this contract, you are expressing this agreement,
- * and you will be able to register the contract as an implementer in the registry for that account.
+ * @dev Implementation of the `IERC1820Implementer` interface.
+ *
+ * Contracts may inherit from this and call `_registerInterfaceForAddress` to
+ * declare their willingness to be implementers.
+ * `IERC1820Registry.setInterfaceImplementer` should then be called for the
+ * registration to be complete.
  */
 contract ERC1820Implementer is IERC1820Implementer {
     bytes32 constant private ERC1820_ACCEPT_MAGIC = keccak256(abi.encodePacked("ERC1820_ACCEPT_MAGIC"));
 
     mapping(bytes32 => mapping(address => bool)) private _supportedInterfaces;
 
+    /**
+     * See `IERC1820Implementer.canImplementInterfaceForAddress`.
+     */
     function canImplementInterfaceForAddress(bytes32 interfaceHash, address account) external view returns (bytes32) {
         return _supportedInterfaces[interfaceHash][account] ? ERC1820_ACCEPT_MAGIC : bytes32(0x00);
     }
 
+    /**
+     * @dev Declares the contract as willing to be an implementer of
+     * `interfaceHash` for `account`.
+     *
+     * See `IERC1820Registry.setInterfaceImplementer` and
+     * `IERC1820Registry.interfaceHash`.
+     */
     function _registerInterfaceForAddress(bytes32 interfaceHash, address account) internal {
         _supportedInterfaces[interfaceHash][account] = true;
     }

contracts/introspection/IERC165.sol

@@ -1,15 +1,22 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title IERC165
- * @dev https://eips.ethereum.org/EIPS/eip-165
+ * @dev Interface of the ERC165 standard, as defined in the
+ * [EIP](https://eips.ethereum.org/EIPS/eip-165).
+ *
+ * Implementers can declare support of contract interfaces, which can then be
+ * queried by others (`ERC165Checker`).
+ *
+ * For an implementation, see `ERC165`.
  */
 interface IERC165 {
     /**
-     * @notice Query if a contract implements an interface
-     * @param interfaceId The interface identifier, as specified in ERC-165
-     * @dev Interface identification is specified in ERC-165. This function
-     * uses less than 30,000 gas.
+     * @dev Returns true if this contract implements the interface defined by
+     * `interfaceId`. See the corresponding
+     * [EIP section](https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified)
+     * to learn more about how these ids are created.
+     *
+     * This function call must use less than 30 000 gas.
      */
     function supportsInterface(bytes4 interfaceId) external view returns (bool);
 }

contracts/introspection/IERC1820Implementer.sol

@@ -1,17 +1,17 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title IERC1820Implementer
- * Interface for contracts that will be registered as implementers in the ERC1820 registry.
- * @notice For more details, see https://eips.ethereum.org/EIPS/eip-1820
+ * @dev Interface for an ERC1820 implementer, as defined in the
+ * [EIP](https://eips.ethereum.org/EIPS/eip-1820#interface-implementation-erc1820implementerinterface).
+ * Used by contracts that will be registered as implementers in the
+ * `IERC1820Registry`.
  */
 interface IERC1820Implementer {
     /**
-     * @notice Indicates whether the contract implements the interface `interfaceHash` for the address `account` or
-     * not.
-     * @param interfaceHash keccak256 hash of the name of the interface
-     * @param account Address for which the contract will implement the interface
-     * @return ERC1820_ACCEPT_MAGIC only if the contract implements `interfaceHash` for the address `account`.
+     * @dev Returns a special value (`ERC1820_ACCEPT_MAGIC`) if this contract
+     * implements `interfaceHash` for `account`.
+     *
+     * See `IERC1820Registry.setInterfaceImplementer`.
      */
     function canImplementInterfaceForAddress(bytes32 interfaceHash, address account) external view returns (bytes32);
 }

contracts/introspection/IERC1820Registry.sol

@@ -1,56 +1,88 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title ERC1820 Pseudo-introspection Registry Contract
- * @author Jordi Baylina and Jacques Dafflon
- * @notice For more details, see https://eips.ethereum.org/EIPS/eip-1820
+ * @dev Interface of the global ERC1820 Registry, as defined in the
+ * [EIP](https://eips.ethereum.org/EIPS/eip-1820). Accounts may register
+ * implementers for interfaces in this registry, as well as query support.
+ *
+ * Implementers may be shared by multiple accounts, and can also implement more
+ * than a single interface for each account. Contracts can implement interfaces
+ * for themselves, but externally-owned accounts (EOA) must delegate this to a
+ * contract.
+ *
+ * `IERC165` interfaces can also be queried via the registry.
+ *
+ * For an in-depth explanation and source code analysis, see the EIP text.
  */
 interface IERC1820Registry {
     /**
-     * @notice Sets the contract which implements a specific interface for an address.
-     * Only the manager defined for that address can set it.
-     * (Each address is the manager for itself until it sets a new manager.)
-     * @param account Address for which to set the interface.
-     * (If 'account' is the zero address then 'msg.sender' is assumed.)
-     * @param interfaceHash Keccak256 hash of the name of the interface as a string.
-     * E.g., 'web3.utils.keccak256("ERC777TokensRecipient")' for the 'ERC777TokensRecipient' interface.
-     * @param implementer Contract address implementing `interfaceHash` for `account.address()`.
+     * @dev Sets `newManager` as the manager for `account`. A manager of an
+     * account is able to set interface implementers for it.
+     *
+     * By default, each account is its own manager. Passing a value of `0x0` in
+     * `newManager` will reset the manager to this initial state.
+     *
+     * Emits a `ManagerChanged` event.
+     *
+     * Requirements:
+     *
+     * - the caller must be the current manager for `account`.
      */
-    function setInterfaceImplementer(address account, bytes32 interfaceHash, address implementer) external;
+    function setManager(address account, address newManager) external;
 
     /**
-     * @notice Sets `newManager.address()` as manager for `account.address()`.
-     * The new manager will be able to call 'setInterfaceImplementer' for `account.address()`.
-     * @param account Address for which to set the new manager.
-     * @param newManager Address of the new manager for `addr.address()`.
-     * (Pass '0x0' to reset the manager to `account.address()`.)
+     * @dev Returns the manager for `account`.
+     *
+     * See `setManager`.
      */
-    function setManager(address account, address newManager) external;
+    function getManager(address account) external view returns (address);
 
     /**
-     *  @notice Updates the cache with whether the contract implements an ERC165 interface or not.
-     *  @param account Address of the contract for which to update the cache.
-     *  @param interfaceId ERC165 interface for which to update the cache.
+     * @dev Sets the `implementer` contract as `account`'s implementer for
+     * `interfaceHash`.
+     *
+     * `account` being the zero address is an alias for the caller's address.
+     * The zero address can also be used in `implementer` to remove an old one.
+     *
+     * See `interfaceHash` to learn how these are created.
+     *
+     * Emits an `InterfaceImplementerSet` event.
+     *
+     * Requirements:
+     *
+     * - the caller must be the current manager for `account`.
+     * - `interfaceHash` must not be an `IERC165` interface id (i.e. it must not
+     * end in 28 zeroes).
+     * - `implementer` must implement `IERC1820Implementer` and return true when
+     * queried for support, unless `implementer` is the caller. See
+     * `IERC1820Implementer.canImplementInterfaceForAddress`.
      */
-    function updateERC165Cache(address account, bytes4 interfaceId) external;
+    function setInterfaceImplementer(address account, bytes32 interfaceHash, address implementer) external;
 
     /**
-     *  @notice Get the manager of an address.
-     *  @param account Address for which to return the manager.
-     *  @return Address of the manager for a given address.
+     * @dev Returns the implementer of `interfaceHash` for `account`. If no such
+     * implementer is registered, returns the zero address.
+     *
+     * If `interfaceHash` is an `IERC165` interface id (i.e. it ends with 28
+     * zeroes), `account` will be queried for support of it.
+     *
+     * `account` being the zero address is an alias for the caller's address.
      */
-    function getManager(address account) external view returns (address);
+    function getInterfaceImplementer(address account, bytes32 interfaceHash) external view returns (address);
 
     /**
-     *  @notice Query if an address implements an interface and through which contract.
-     *  @param account Address being queried for the implementer of an interface.
-     *  (If 'account' is the zero address then 'msg.sender' is assumed.)
-     *  @param interfaceHash Keccak256 hash of the name of the interface as a string.
-     *  E.g., 'web3.utils.keccak256("ERC777TokensRecipient")' for the 'ERC777TokensRecipient' interface.
-     *  @return The address of the contract which implements the interface `interfaceHash` for `account.address()`
-     *  or '0' if `account.address()` did not register an implementer for this interface.
+     * @dev Returns the interface hash for an `interfaceName`, as defined in the
+     * corresponding
+     * [section of the EIP](https://eips.ethereum.org/EIPS/eip-1820#interface-name).
      */
-    function getInterfaceImplementer(address account, bytes32 interfaceHash) external view returns (address);
+    function interfaceHash(string calldata interfaceName) external pure returns (bytes32);
+
+    /**
+     *  @notice Updates the cache with whether the contract implements an ERC165 interface or not.
+     *  @param account Address of the contract for which to update the cache.
+     *  @param interfaceId ERC165 interface for which to update the cache.
+     */
+    function updateERC165Cache(address account, bytes4 interfaceId) external;
 
     /**
      *  @notice Checks whether a contract implements an ERC165 interface or not.
@@ -71,20 +103,7 @@ interface IERC1820Registry {
      */
     function implementsERC165InterfaceNoCache(address account, bytes4 interfaceId) external view returns (bool);
 
-    /**
-     *  @notice Compute the keccak256 hash of an interface given its name.
-     *  @param interfaceName Name of the interface.
-     *  @return The keccak256 hash of an interface name.
-     */
-    function interfaceHash(string calldata interfaceName) external pure returns (bytes32);
-
-    /**
-     *  @notice Indicates a contract is the `implementer` of `interfaceHash` for `account`.
-     */
     event InterfaceImplementerSet(address indexed account, bytes32 indexed interfaceHash, address indexed implementer);
 
-    /**
-     *  @notice Indicates `newManager` is the address of the new manager for `account`.
-     */
     event ManagerChanged(address indexed account, address indexed newManager);
 }

contracts/introspection/README.md

@@ -0,0 +1,23 @@
+---
+sections:
+  - title: Local
+    contracts:
+      - IERC165
+      - ERC165
+      - ERC165Checker
+  - title: Global
+    contracts:
+      - IERC1820Registry
+      - IERC1820Implementer
+      - ERC1820Implementer
+---
+
+This set of interfaces and contracts deal with [type introspection](https://en.wikipedia.org/wiki/Type_introspection) of contracts, that is, examining which functions can be called on them. This is usually referred to as a contract's _interface_.
+
+Ethereum contracts have no native concept of an interface, so applications must usually simply trust they are not making an incorrect call. For trusted setups this is a non-issue, but often unknown and untrusted third-party addresses need to be interacted with. There may even not be any direct calls to them! (e.g. `ERC20` tokens may be sent to a contract that lacks a way to transfer them out of it, locking them forever). In these cases, a contract _declaring_ its interface can be very helpful in preventing errors.
+
+There are two main ways to approach this.
+ - Locally, where a contract implements `IERC165` and declares an interface, and a second one queries it directly via `ERC165Checker`.
+ - Globally, where a global and unique registry (`IERC1820Registry`) is used to register implementers of a certain interface (`IERC1820Implementer`). It is then the registry that is queried, which allows for more complex setups, like contracts implementing interfaces for externally-owned accounts.
+
+Note that, in all cases, accounts simply _declare_ their interfaces, but they are not required to actually implement them. This mechanism can therefore be used to both prevent errors and allow for complex interactions (see `ERC777`), but it must not be relied on for security.

contracts/lifecycle/Pausable.sol

@@ -3,21 +3,37 @@ pragma solidity ^0.5.0;
 import "../access/roles/PauserRole.sol";
 
 /**
- * @title Pausable
- * @dev Base contract which allows children to implement an emergency stop mechanism.
+ * @dev Contract module which allows children to implement an emergency stop
+ * mechanism that can be triggered by an authorized account.
+ *
+ * This module is used through inheritance. It will make available the
+ * modifiers `whenNotPaused` and `whenPaused`, which can be applied to
+ * the functions of your contract. Note that they will not be pausable by
+ * simply including this module, only once the modifiers are put in place.
  */
 contract Pausable is PauserRole {
+    /**
+     * @dev Emitted when the pause is triggered by a pauser (`account`).
+     */
     event Paused(address account);
+
+    /**
+     * @dev Emitted when the pause is lifted by a pauser (`account`).
+     */
     event Unpaused(address account);
 
     bool private _paused;
 
+    /**
+     * @dev Initializes the contract in unpaused state. Assigns the Pauser role
+     * to the deployer.
+     */
     constructor () internal {
         _paused = false;
     }
 
     /**
-     * @return True if the contract is paused, false otherwise.
+     * @dev Returns true if the contract is paused, and false otherwise.
      */
     function paused() public view returns (bool) {
         return _paused;

contracts/math/Math.sol

@@ -1,8 +1,7 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title Math
- * @dev Assorted math operations.
+ * @dev Standard math utilities missing in the Solidity language.
  */
 library Math {
     /**
@@ -20,9 +19,8 @@ library Math {
     }
 
     /**
-     * @dev Calculates the average of two numbers. Since these are integers,
-     * averages of an even and odd number cannot be represented, and will be
-     * rounded down.
+     * @dev Returns the average of two numbers. The result is rounded towards
+     * zero.
      */
     function average(uint256 a, uint256 b) internal pure returns (uint256) {
         // (a + b) / 2 can overflow, so we distribute

contracts/math/README.md

@@ -0,0 +1,10 @@
+---
+title: Math
+sections:
+  - title: Libraries
+    contracts:
+      - SafeMath
+      - Math
+---
+
+These are math-related utilities.

contracts/math/SafeMath.sol

@@ -1,12 +1,59 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title SafeMath
- * @dev Unsigned math operations with safety checks that revert on error.
+ * @dev Wrappers over Solidity's arithmetic operations with added overflow
+ * checks.
+ *
+ * Arithmetic operations in Solidity wrap on overflow. This can easily result
+ * in bugs, because programmers usually assume that an overflow raises an
+ * error, which is the standard behavior in high level programming languages.
+ * `SafeMath` restores this intuition by reverting the transaction when an
+ * operation overflows.
+ *
+ * Using this library instead of the unchecked operations eliminates an entire
+ * class of bugs, so it's recommended to use it always.
  */
 library SafeMath {
     /**
-     * @dev Multiplies two unsigned integers, reverts on overflow.
+     * @dev Returns the addition of two unsigned integers, reverting on
+     * overflow.
+     *
+     * Counterpart to Solidity's `+` operator.
+     *
+     * Requirements:
+     * - Addition cannot overflow.
+     */
+    function add(uint256 a, uint256 b) internal pure returns (uint256) {
+        uint256 c = a + b;
+        require(c >= a, "SafeMath: addition overflow");
+
+        return c;
+    }
+
+    /**
+     * @dev Returns the subtraction of two unsigned integers, reverting on
+     * overflow (when the result is negative).
+     *
+     * Counterpart to Solidity's `-` operator.
+     *
+     * Requirements:
+     * - Subtraction cannot overflow.
+     */
+    function sub(uint256 a, uint256 b) internal pure returns (uint256) {
+        require(b <= a, "SafeMath: subtraction overflow");
+        uint256 c = a - b;
+
+        return c;
+    }
+
+    /**
+     * @dev Returns the multiplication of two unsigned integers, reverting on
+     * overflow.
+     *
+     * Counterpart to Solidity's `*` operator.
+     *
+     * Requirements:
+     * - Multiplication cannot overflow.
      */
     function mul(uint256 a, uint256 b) internal pure returns (uint256) {
         // Gas optimization: this is cheaper than requiring 'a' not being zero, but the
@@ -23,7 +70,15 @@ library SafeMath {
     }
 
     /**
-     * @dev Integer division of two unsigned integers truncating the quotient, reverts on division by zero.
+     * @dev Returns the integer division of two unsigned integers. Reverts on
+     * division by zero. The result is rounded towards zero.
+     *
+     * Counterpart to Solidity's `/` operator. Note: this function uses a
+     * `revert` opcode (which leaves remaining gas untouched) while Solidity
+     * uses an invalid opcode to revert (consuming all remaining gas).
+     *
+     * Requirements:
+     * - The divisor cannot be zero.
      */
     function div(uint256 a, uint256 b) internal pure returns (uint256) {
         // Solidity only automatically asserts when dividing by 0
@@ -35,28 +90,15 @@ library SafeMath {
     }
 
     /**
-     * @dev Subtracts two unsigned integers, reverts on overflow (i.e. if subtrahend is greater than minuend).
-     */
-    function sub(uint256 a, uint256 b) internal pure returns (uint256) {
-        require(b <= a, "SafeMath: subtraction overflow");
-        uint256 c = a - b;
-
-        return c;
-    }
-
-    /**
-     * @dev Adds two unsigned integers, reverts on overflow.
-     */
-    function add(uint256 a, uint256 b) internal pure returns (uint256) {
-        uint256 c = a + b;
-        require(c >= a, "SafeMath: addition overflow");
-
-        return c;
-    }
-
-    /**
-     * @dev Divides two unsigned integers and returns the remainder (unsigned integer modulo),
-     * reverts when dividing by zero.
+     * @dev Returns the remainder of dividing two unsigned integers. (unsigned integer modulo),
+     * Reverts when dividing by zero.
+     *
+     * Counterpart to Solidity's `%` operator. This function uses a `revert`
+     * opcode (which leaves remaining gas untouched) while Solidity uses an
+     * invalid opcode to revert (consuming all remaining gas).
+     *
+     * Requirements:
+     * - The divisor cannot be zero.
      */
     function mod(uint256 a, uint256 b) internal pure returns (uint256) {
         require(b != 0, "SafeMath: modulo by zero");

contracts/ownership/Ownable.sol

@@ -1,9 +1,13 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title Ownable
- * @dev The Ownable contract has an owner address, and provides basic authorization control
- * functions, this simplifies the implementation of "user permissions".
+ * @dev Contract module which provides a basic access control mechanism, where
+ * there is an account (an owner) that can be granted exclusive access to
+ * specific functions.
+ *
+ * This module is used through inheritance. It will make available the modifier
+ * `onlyOwner`, which can be aplied to your functions to restrict their use to
+ * the owner.
  */
 contract Ownable {
     address private _owner;
@@ -11,8 +15,7 @@ contract Ownable {
     event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);
 
     /**
-     * @dev The Ownable constructor sets the original `owner` of the contract to the sender
-     * account.
+     * @dev Initializes the contract setting the deployer as the initial owner.
      */
     constructor () internal {
         _owner = msg.sender;
@@ -20,7 +23,7 @@ contract Ownable {
     }
 
     /**
-     * @return the address of the owner.
+     * @dev Returns the address of the current owner.
      */
     function owner() public view returns (address) {
         return _owner;
@@ -35,17 +38,17 @@ contract Ownable {
     }
 
     /**
-     * @return true if `msg.sender` is the owner of the contract.
+     * @dev Returns true if the caller is the current owner.
      */
     function isOwner() public view returns (bool) {
         return msg.sender == _owner;
     }
 
     /**
-     * @dev Allows the current owner to relinquish control of the contract.
-     * It will not be possible to call the functions with the `onlyOwner`
-     * modifier anymore.
-     * @notice Renouncing ownership will leave the contract without an owner,
+     * @dev Leaves the contract without owner. It will not be possible to call
+     * `onlyOwner` functions anymore. Can only be called by the current owner.
+     *
+     * > Note: Renouncing ownership will leave the contract without an owner,
      * thereby removing any functionality that is only available to the owner.
      */
     function renounceOwnership() public onlyOwner {
@@ -54,16 +57,15 @@ contract Ownable {
     }
 
     /**
-     * @dev Allows the current owner to transfer control of the contract to a newOwner.
-     * @param newOwner The address to transfer ownership to.
+     * @dev Transfers ownership of the contract to a new account (`newOwner`).
+     * Can only be called by the current owner.
      */
     function transferOwnership(address newOwner) public onlyOwner {
         _transferOwnership(newOwner);
     }
 
     /**
-     * @dev Transfers control of the contract to a newOwner.
-     * @param newOwner The address to transfer ownership to.
+     * @dev Transfers ownership of the contract to a new account (`newOwner`).
      */
     function _transferOwnership(address newOwner) internal {
         require(newOwner != address(0), "Ownable: new owner is the zero address");

contracts/ownership/README.md

@@ -0,0 +1,3 @@
+Contract modules for simple authorization and access control mechanisms.
+
+For more complex needs see [Access](access).

contracts/ownership/Secondary.sol

@@ -1,12 +1,14 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title Secondary
  * @dev A Secondary contract can only be used by its primary account (the one that created it).
  */
 contract Secondary {
     address private _primary;
 
+    /**
+     * @dev Emitted when the primary contract changes.
+     */
     event PrimaryTransferred(
         address recipient
     );

contracts/payment/README.md

@@ -0,0 +1,10 @@
+---
+sections:
+  - title: Payment Utilities
+    contracts:
+      - PaymentSplitter
+      - PullPayment
+  - subdirectory: escrow
+---
+
+> This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/payment/escrow/README.md

@@ -0,0 +1,8 @@
+---
+title: Escrows
+sections:
+  - contracts:
+    - Escrow
+    - ConditionalEscrow
+    - RefundEscrow
+---

contracts/token/ERC20/ERC20.sol

@@ -4,16 +4,27 @@ import "./IERC20.sol";
 import "../../math/SafeMath.sol";
 
 /**
- * @title Standard ERC20 token
+ * @dev Implementation of the `IERC20` interface.
  *
- * @dev Implementation of the basic standard token.
- * https://eips.ethereum.org/EIPS/eip-20
- * Originally based on code by FirstBlood:
- * https://github.com/Firstbloodio/token/blob/master/smart_contract/FirstBloodToken.sol
+ * This implementation is agnostic to the way tokens are created. This means
+ * that a supply mechanism has to be added in a derived contract using `_mint`.
+ * For a generic mechanism see `ERC20Mintable`.
  *
- * This implementation emits additional Approval events, allowing applications to reconstruct the allowance status for
- * all accounts just by listening to said events. Note that this isn't required by the specification, and other
- * compliant implementations may not do it.
+ * *For a detailed writeup see our guide [How to implement supply
+ * mechanisms](https://forum.zeppelin.solutions/t/how-to-implement-erc20-supply-mechanisms/226).*
+ *
+ * We have followed general OpenZeppelin guidelines: functions revert instead
+ * of returning `false` on failure. This behavior is nonetheless conventional
+ * and does not conflict with the expectations of ERC20 applications.
+ *
+ * Additionally, an `Approval` event is emitted on calls to `transferFrom`.
+ * This allows applications to reconstruct the allowance for all accounts just
+ * by listening to said events. Other implementations of the EIP may not emit
+ * these events, as it isn't required by the specification.
+ *
+ * Finally, the non-standard `decreaseAllowance` and `increaseAllowance`
+ * functions have been added to mitigate the well-known issues around setting
+ * allowances. See `IERC20.approve`.
  */
 contract ERC20 is IERC20 {
     using SafeMath for uint256;
@@ -25,49 +36,45 @@ contract ERC20 is IERC20 {
     uint256 private _totalSupply;
 
     /**
-     * @dev Total number of tokens in existence.
+     * @dev See `IERC20.totalSupply`.
      */
     function totalSupply() public view returns (uint256) {
         return _totalSupply;
     }
 
     /**
-     * @dev Gets the balance of the specified address.
-     * @param owner The address to query the balance of.
-     * @return A uint256 representing the amount owned by the passed address.
+     * @dev See `IERC20.balanceOf`.
      */
-    function balanceOf(address owner) public view returns (uint256) {
-        return _balances[owner];
+    function balanceOf(address account) public view returns (uint256) {
+        return _balances[account];
     }
 
     /**
-     * @dev Function to check the amount of tokens that an owner allowed to a spender.
-     * @param owner address The address which owns the funds.
-     * @param spender address The address which will spend the funds.
-     * @return A uint256 specifying the amount of tokens still available for the spender.
+     * @dev See `IERC20.transfer`.
+     *
+     * Requirements:
+     *
+     * - `recipient` cannot be the zero address.
+     * - the caller must have a balance of at least `amount`.
      */
-    function allowance(address owner, address spender) public view returns (uint256) {
-        return _allowances[owner][spender];
+    function transfer(address recipient, uint256 amount) public returns (bool) {
+        _transfer(msg.sender, recipient, amount);
+        return true;
     }
 
     /**
-     * @dev Transfer token to a specified address.
-     * @param to The address to transfer to.
-     * @param value The amount to be transferred.
+     * @dev See `IERC20.allowance`.
      */
-    function transfer(address to, uint256 value) public returns (bool) {
-        _transfer(msg.sender, to, value);
-        return true;
+    function allowance(address owner, address spender) public view returns (uint256) {
+        return _allowances[owner][spender];
     }
 
     /**
-     * @dev Approve the passed address to spend the specified amount of tokens on behalf of msg.sender.
-     * Beware that changing an allowance with this method brings the risk that someone may use both the old
-     * and the new allowance by unfortunate transaction ordering. One possible solution to mitigate this
-     * race condition is to first reduce the spender's allowance to 0 and set the desired value afterwards:
-     * https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729
-     * @param spender The address which will spend the funds.
-     * @param value The amount of tokens to be spent.
+     * @dev See `IERC20.approve`.
+     *
+     * Requirements:
+     *
+     * - `spender` cannot be the zero address.
      */
     function approve(address spender, uint256 value) public returns (bool) {
         _approve(msg.sender, spender, value);
@@ -75,28 +82,34 @@ contract ERC20 is IERC20 {
     }
 
     /**
-     * @dev Transfer tokens from one address to another.
-     * Note that while this function emits an Approval event, this is not required as per the specification,
-     * and other compliant implementations may not emit the event.
-     * @param from address The address which you want to send tokens from
-     * @param to address The address which you want to transfer to
-     * @param value uint256 the amount of tokens to be transferred
+     * @dev See `IERC20.transferFrom`.
+     *
+     * Emits an `Approval` event indicating the updated allowance. This is not
+     * required by the EIP. See the note at the beginning of `ERC20`;
+     *
+     * Requirements:
+     * - `sender` and `recipient` cannot be the zero address.
+     * - `sender` must have a balance of at least `value`.
+     * - the caller must have allowance for `sender`'s tokens of at least
+     * `amount`.
      */
-    function transferFrom(address from, address to, uint256 value) public returns (bool) {
-        _transfer(from, to, value);
-        _approve(from, msg.sender, _allowances[from][msg.sender].sub(value));
+    function transferFrom(address sender, address recipient, uint256 amount) public returns (bool) {
+        _transfer(sender, recipient, amount);
+        _approve(sender, msg.sender, _allowances[sender][msg.sender].sub(amount));
         return true;
     }
 
     /**
-     * @dev Increase the amount of tokens that an owner allowed to a spender.
-     * approve should be called when _allowances[msg.sender][spender] == 0. To increment
-     * allowed value is better to use this function to avoid 2 calls (and wait until
-     * the first transaction is mined)
-     * From MonolithDAO Token.sol
-     * Emits an Approval event.
-     * @param spender The address which will spend the funds.
-     * @param addedValue The amount of tokens to increase the allowance by.
+     * @dev Atomically increases the allowance granted to `spender` by the caller.
+     *
+     * This is an alternative to `approve` that can be used as a mitigation for
+     * problems described in `IERC20.approve`.
+     *
+     * Emits an `Approval` event indicating the updated allowance.
+     *
+     * Requirements:
+     *
+     * - `spender` cannot be the zero address.
      */
     function increaseAllowance(address spender, uint256 addedValue) public returns (bool) {
         _approve(msg.sender, spender, _allowances[msg.sender][spender].add(addedValue));
@@ -104,14 +117,18 @@ contract ERC20 is IERC20 {
     }
 
     /**
-     * @dev Decrease the amount of tokens that an owner allowed to a spender.
-     * approve should be called when _allowances[msg.sender][spender] == 0. To decrement
-     * allowed value is better to use this function to avoid 2 calls (and wait until
-     * the first transaction is mined)
-     * From MonolithDAO Token.sol
-     * Emits an Approval event.
-     * @param spender The address which will spend the funds.
-     * @param subtractedValue The amount of tokens to decrease the allowance by.
+     * @dev Atomically decreases the allowance granted to `spender` by the caller.
+     *
+     * This is an alternative to `approve` that can be used as a mitigation for
+     * problems described in `IERC20.approve`.
+     *
+     * Emits an `Approval` event indicating the updated allowance.
+     *
+     * Requirements:
+     *
+     * - `spender` cannot be the zero address.
+     * - `spender` must have allowance for the caller of at least
+     * `subtractedValue`.
      */
     function decreaseAllowance(address spender, uint256 subtractedValue) public returns (bool) {
         _approve(msg.sender, spender, _allowances[msg.sender][spender].sub(subtractedValue));
@@ -119,40 +136,55 @@ contract ERC20 is IERC20 {
     }
 
     /**
-     * @dev Transfer token for a specified addresses.
-     * @param from The address to transfer from.
-     * @param to The address to transfer to.
-     * @param value The amount to be transferred.
+     * @dev Moves tokens `amount` from `sender` to `recipient`.
+     *
+     * This is internal function is equivalent to `transfer`, and can be used to
+     * e.g. implement automatic token fees, slashing mechanisms, etc.
+     *
+     * Emits a `Transfer` event.
+     *
+     * Requirements:
+     *
+     * - `sender` cannot be the zero address.
+     * - `recipient` cannot be the zero address.
+     * - `sender` must have a balance of at least `amount`.
      */
-    function _transfer(address from, address to, uint256 value) internal {
-        require(from != address(0), "ERC20: transfer from the zero address");
-        require(to != address(0), "ERC20: transfer to the zero address");
+    function _transfer(address sender, address recipient, uint256 amount) internal {
+        require(sender != address(0), "ERC20: transfer from the zero address");
+        require(recipient != address(0), "ERC20: transfer to the zero address");
 
-        _balances[from] = _balances[from].sub(value);
-        _balances[to] = _balances[to].add(value);
-        emit Transfer(from, to, value);
+        _balances[sender] = _balances[sender].sub(amount);
+        _balances[recipient] = _balances[recipient].add(amount);
+        emit Transfer(sender, recipient, amount);
     }
 
-    /**
-     * @dev Internal function that mints an amount of the token and assigns it to
-     * an account. This encapsulates the modification of balances such that the
-     * proper events are emitted.
-     * @param account The account that will receive the created tokens.
-     * @param value The amount that will be created.
+    /** @dev Creates `amount` tokens and assigns them to `account`, increasing
+     * the total supply.
+     *
+     * Emits a `Transfer` event with `from` set to the zero address.
+     *
+     * Requirements
+     *
+     * - `to` cannot be the zero address.
      */
-    function _mint(address account, uint256 value) internal {
+    function _mint(address account, uint256 amount) internal {
         require(account != address(0), "ERC20: mint to the zero address");
 
-        _totalSupply = _totalSupply.add(value);
-        _balances[account] = _balances[account].add(value);
-        emit Transfer(address(0), account, value);
+        _totalSupply = _totalSupply.add(amount);
+        _balances[account] = _balances[account].add(amount);
+        emit Transfer(address(0), account, amount);
     }
 
-    /**
-     * @dev Internal function that burns an amount of the token of a given
-     * account.
-     * @param account The account whose tokens will be burnt.
-     * @param value The amount that will be burnt.
+     /**
+     * @dev Destoys `amount` tokens from `account`, reducing the
+     * total supply.
+     *
+     * Emits a `Transfer` event with `to` set to the zero address.
+     *
+     * Requirements
+     *
+     * - `account` cannot be the zero address.
+     * - `account` must have at least `amount` tokens.
      */
     function _burn(address account, uint256 value) internal {
         require(account != address(0), "ERC20: burn from the zero address");
@@ -163,10 +195,17 @@ contract ERC20 is IERC20 {
     }
 
     /**
-     * @dev Approve an address to spend another addresses' tokens.
-     * @param owner The address that owns the tokens.
-     * @param spender The address that will spend the tokens.
-     * @param value The number of tokens that can be spent.
+     * @dev Sets `amount` as the allowance of `spender` over the `owner`s tokens.
+     *
+     * This is internal function is equivalent to `approve`, and can be used to
+     * e.g. set automatic allowances for certain subsystems, etc.
+     *
+     * Emits an `Approval` event.
+     *
+     * Requirements:
+     *
+     * - `owner` cannot be the zero address.
+     * - `spender` cannot be the zero address.
      */
     function _approve(address owner, address spender, uint256 value) internal {
         require(owner != address(0), "ERC20: approve from the zero address");
@@ -177,15 +216,13 @@ contract ERC20 is IERC20 {
     }
 
     /**
-     * @dev Internal function that burns an amount of the token of a given
-     * account, deducting from the sender's allowance for said account. Uses the
-     * internal burn function.
-     * Emits an Approval event (reflecting the reduced allowance).
-     * @param account The account whose tokens will be burnt.
-     * @param value The amount that will be burnt.
+     * @dev Destoys `amount` tokens from `account`.`amount` is then deducted
+     * from the caller's allowance.
+     *
+     * See `_burn` and `_approve`.
      */
-    function _burnFrom(address account, uint256 value) internal {
-        _burn(account, value);
-        _approve(account, msg.sender, _allowances[account][msg.sender].sub(value));
+    function _burnFrom(address account, uint256 amount) internal {
+        _burn(account, amount);
+        _approve(account, msg.sender, _allowances[account][msg.sender].sub(amount));
     }
 }

contracts/token/ERC20/ERC20Burnable.sol

@@ -3,24 +3,24 @@ pragma solidity ^0.5.0;
 import "./ERC20.sol";
 
 /**
- * @title Burnable Token
- * @dev Token that can be irreversibly burned (destroyed).
+ * @dev Extension of `ERC20` that allows token holders to destroy both their own
+ * tokens and those that they have an allowance for, in a way that can be
+ * recognized off-chain (via event analysis).
  */
 contract ERC20Burnable is ERC20 {
     /**
-     * @dev Burns a specific amount of tokens.
-     * @param value The amount of token to be burned.
+     * @dev Destoys `amount` tokens from the caller.
+     *
+     * See `ERC20._burn`.
      */
-    function burn(uint256 value) public {
-        _burn(msg.sender, value);
+    function burn(uint256 amount) public {
+        _burn(msg.sender, amount);
     }
 
     /**
-     * @dev Burns a specific amount of tokens from the target address and decrements allowance.
-     * @param from address The account whose tokens will be burned.
-     * @param value uint256 The amount of token to be burned.
+     * @dev See `ERC20._burnFrom`.
      */
-    function burnFrom(address from, uint256 value) public {
-        _burnFrom(from, value);
+    function burnFrom(address account, uint256 amount) public {
+        _burnFrom(account, amount);
     }
 }

contracts/token/ERC20/ERC20Capped.sol

@@ -3,24 +3,34 @@ pragma solidity ^0.5.0;
 import "./ERC20Mintable.sol";
 
 /**
- * @title Capped token
- * @dev Mintable token with a token cap.
+ * @dev Extension of `ERC20Mintable` that adds a cap to the supply of tokens.
  */
 contract ERC20Capped is ERC20Mintable {
     uint256 private _cap;
 
+    /**
+     * @dev Sets the value of the `cap`. This value is immutable, it can only be
+     * set once during construction.
+     */
     constructor (uint256 cap) public {
         require(cap > 0, "ERC20Capped: cap is 0");
         _cap = cap;
     }
 
     /**
-     * @return the cap for the token minting.
+     * @dev Returns the cap on the token's total supply.
      */
     function cap() public view returns (uint256) {
         return _cap;
     }
 
+    /**
+     * @dev See `ERC20Mintable.mint`.
+     *
+     * Requirements:
+     *
+     * - `value` must not cause the total supply to go over the cap.
+     */
     function _mint(address account, uint256 value) internal {
         require(totalSupply().add(value) <= _cap, "ERC20Capped: cap exceeded");
         super._mint(account, value);

contracts/token/ERC20/ERC20Detailed.sol

@@ -3,16 +3,18 @@ pragma solidity ^0.5.0;
 import "./IERC20.sol";
 
 /**
- * @title ERC20Detailed token
- * @dev The decimals are only for visualization purposes.
- * All the operations are done using the smallest and indivisible token unit,
- * just as on Ethereum all the operations are done in wei.
+ * @dev Optional functions from the ERC20 standard.
  */
 contract ERC20Detailed is IERC20 {
     string private _name;
     string private _symbol;
     uint8 private _decimals;
 
+    /**
+     * @dev Sets the values for `name`, `symbol`, and `decimals`. All three of
+     * these values are immutable: they can only be set once during
+     * construction.
+     */
     constructor (string memory name, string memory symbol, uint8 decimals) public {
         _name = name;
         _symbol = symbol;
@@ -20,21 +22,31 @@ contract ERC20Detailed is IERC20 {
     }
 
     /**
-     * @return the name of the token.
+     * @dev Returns the name of the token.
      */
     function name() public view returns (string memory) {
         return _name;
     }
 
     /**
-     * @return the symbol of the token.
+     * @dev Returns the symbol of the token, usually a shorter version of the
+     * name.
      */
     function symbol() public view returns (string memory) {
         return _symbol;
     }
 
     /**
-     * @return the number of decimals of the token.
+     * @dev Returns the number of decimals used to get its user representation.
+     * For example, if `decimals` equals `2`, a balance of `505` tokens should
+     * be displayed to a user as `5,05` (`505 / 10 ** 2`).
+     *
+     * Tokens usually opt for a value of 18, imitating the relationship between
+     * Ether and Wei.
+     *
+     * > Note that this information is only used for _display_ purposes: it in
+     * no way affects any of the arithmetic of the contract, including
+     * `IERC20.balanceOf` and `IERC20.transfer`.
      */
     function decimals() public view returns (uint8) {
         return _decimals;

contracts/token/ERC20/ERC20Mintable.sol

@@ -4,18 +4,21 @@ import "./ERC20.sol";
 import "../../access/roles/MinterRole.sol";
 
 /**
- * @title ERC20Mintable
- * @dev ERC20 minting logic.
+ * @dev Extension of `ERC20` that adds a set of accounts with the `MinterRole`,
+ * which have permission to mint (create) new tokens as they see fit.
+ *
+ * At construction, the deployer of the contract is the only minter.
  */
 contract ERC20Mintable is ERC20, MinterRole {
     /**
-     * @dev Function to mint tokens
-     * @param to The address that will receive the minted tokens.
-     * @param value The amount of tokens to mint.
-     * @return A boolean that indicates if the operation was successful.
+     * @dev See `ERC20._mint`.
+     *
+     * Requirements:
+     *
+     * - the caller must have the `MinterRole`.
      */
-    function mint(address to, uint256 value) public onlyMinter returns (bool) {
-        _mint(to, value);
+    function mint(address account, uint256 amount) public onlyMinter returns (bool) {
+        _mint(account, amount);
         return true;
     }
 }

contracts/token/ERC20/IERC20.sol

@@ -1,23 +1,76 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title ERC20 interface
- * @dev see https://eips.ethereum.org/EIPS/eip-20
+ * @dev Interface of the ERC20 standard as defined in the EIP. Does not include
+ * the optional functions; to access them see `ERC20Detailed`.
  */
 interface IERC20 {
-    function transfer(address to, uint256 value) external returns (bool);
+    /**
+     * @dev Returns the amount of tokens in existence.
+     */
+    function totalSupply() external view returns (uint256);
 
-    function approve(address spender, uint256 value) external returns (bool);
+    /**
+     * @dev Returns the amount of tokens owned by `account`.
+     */
+    function balanceOf(address account) external view returns (uint256);
 
-    function transferFrom(address from, address to, uint256 value) external returns (bool);
+    /**
+     * @dev Moves `amount` tokens from the caller's account to `recipient`.
+     *
+     * Returns a boolean value indicating whether the operation succeeded.
+     *
+     * Emits a `Transfer` event.
+     */
+    function transfer(address recipient, uint256 amount) external returns (bool);
 
-    function totalSupply() external view returns (uint256);
+    /**
+     * @dev Returns the remaining number of tokens that `spender` will be
+     * allowed to spend on behalf of `owner` through `transferFrom`. This is
+     * zero by default.
+     *
+     * This value changes when `approve` or `transferFrom` are called.
+     */
+    function allowance(address owner, address spender) external view returns (uint256);
 
-    function balanceOf(address who) external view returns (uint256);
+    /**
+     * @dev Sets `amount` as the allowance of `spender` over the caller's tokens.
+     *
+     * Returns a boolean value indicating whether the operation succeeded.
+     *
+     * > Beware that changing an allowance with this method brings the risk
+     * that someone may use both the old and the new allowance by unfortunate
+     * transaction ordering. One possible solution to mitigate this race
+     * condition is to first reduce the spender's allowance to 0 and set the
+     * desired value afterwards:
+     * https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729
+     *
+     * Emits an `Approval` event.
+     */
+    function approve(address spender, uint256 amount) external returns (bool);
 
-    function allowance(address owner, address spender) external view returns (uint256);
+    /**
+     * @dev Moves `amount` tokens from `sender` to `recipient` using the
+     * allowance mechanism. `amount` is then deducted from the caller's
+     * allowance.
+     *
+     * Returns a boolean value indicating whether the operation succeeded.
+     *
+     * Emits a `Transfer` event.
+     */
+    function transferFrom(address sender, address recipient, uint256 amount) external returns (bool);
 
+    /**
+     * @dev Emitted when `value` tokens are moved from one account (`from`) to
+     * another (`to`).
+     *
+     * Note that `value` may be zero.
+     */
     event Transfer(address indexed from, address indexed to, uint256 value);
 
+    /**
+     * @dev Emitted when the allowance of a `spender` for an `owner` is set by
+     * a call to `approve`. `value` is the new allowance.
+     */
     event Approval(address indexed owner, address indexed spender, uint256 value);
 }

contracts/token/ERC20/README.md

@@ -1,18 +1,35 @@
 ---
 sections:
-  - title: Interfaces
+  - title: Core
     contracts:
       - IERC20
-  - title: Contracts
-    contracts:
       - ERC20
       - ERC20Detailed
+  - title: Extensions
+    contracts:
       - ERC20Mintable
       - ERC20Burnable
-      - ERC20Capped
       - ERC20Pausable
+      - ERC20Capped
   - title: Utilities
     contracts:
       - SafeERC20
       - TokenTimelock
 ---
+
+This set of interfaces, contracts, and utilities are all related to the [ERC20 Token Standard](https://eips.ethereum.org/EIPS/eip-20).
+
+*For a walkthrough on how to create an ERC20 token read our [ERC20 guide](../../tokens.md#constructing-a-nice-erc20-token).*
+
+There a few core contracts that implement the behavior specified in the EIP: `IERC20`, `ERC20`, `ERC20Detailed`.
+
+Additionally there are multiple extensions, including:
+- designation of addresses that can create token supply (`ERC20Mintable`), with an optional maximum cap (`ERC20Capped`),
+- destruction of own tokens (`ERC20Burnable`),
+- designation of addresses that can pause token operations for all users (`ERC20Pausable`).
+
+Finally, there are some utilities to interact with ERC20 contracts in various ways.
+- `SafeERC20` is a wrapper around the interface that eliminates the need to handle boolean return values.
+- `TokenTimelock` can hold tokens for a beneficiary until a specified time.
+
+> This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/token/ERC721/ERC721.sol

@@ -268,6 +268,8 @@ contract ERC721 is ERC165, IERC721 {
     /**
      * @dev Internal function to invoke `onERC721Received` on a target address.
      * The call is not executed if the target address is not a contract.
+     *
+     * This function is deprecated.
      * @param from address representing the previous owner of the given token ID
      * @param to target address that will receive the tokens
      * @param tokenId uint256 ID of the token to be transferred

contracts/token/ERC721/IERC721.sol

@@ -3,25 +3,51 @@ pragma solidity ^0.5.0;
 import "../../introspection/IERC165.sol";
 
 /**
- * @title ERC721 Non-Fungible Token Standard basic interface
- * @dev see https://eips.ethereum.org/EIPS/eip-721
+ * @dev Required interface of an ERC721 compliant contract.
  */
 contract IERC721 is IERC165 {
     event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);
     event Approval(address indexed owner, address indexed approved, uint256 indexed tokenId);
     event ApprovalForAll(address indexed owner, address indexed operator, bool approved);
 
+    /**
+     * @dev Returns the number of NFTs in `owner`'s account.
+     */
     function balanceOf(address owner) public view returns (uint256 balance);
+
+    /**
+     * @dev Returns the owner of the NFT specified by `tokenId`.
+     */
     function ownerOf(uint256 tokenId) public view returns (address owner);
 
+    /**
+     * @dev Transfers a specific NFT (`tokenId`) from one account (`from`) to
+     * another (`to`).
+     *
+     * 
+     *
+     * Requirements:
+     * - `from`, `to` cannot be zero.
+     * - `tokenId` must be owned by `from`.
+     * - If the caller is not `from`, it must be have been allowed to move this
+     * NFT by either `approve` or `setApproveForAll`.
+     */
+    function safeTransferFrom(address from, address to, uint256 tokenId) public;
+    /**
+     * @dev Transfers a specific NFT (`tokenId`) from one account (`from`) to
+     * another (`to`).
+     *
+     * Requirements:
+     * - If the caller is not `from`, it must be approved to move this NFT by
+     * either `approve` or `setApproveForAll`.
+     */
+    function transferFrom(address from, address to, uint256 tokenId) public;
     function approve(address to, uint256 tokenId) public;
     function getApproved(uint256 tokenId) public view returns (address operator);
 
     function setApprovalForAll(address operator, bool _approved) public;
     function isApprovedForAll(address owner, address operator) public view returns (bool);
 
-    function transferFrom(address from, address to, uint256 tokenId) public;
-    function safeTransferFrom(address from, address to, uint256 tokenId) public;
 
     function safeTransferFrom(address from, address to, uint256 tokenId, bytes memory data) public;
 }

contracts/token/ERC721/README.md

@@ -0,0 +1,37 @@
+---
+sections:
+  - title: Core
+    contracts:
+      - IERC721
+      - ERC721
+      - IERC721Metadata
+      - ERC721Metadata
+      - ERC721Enumerable
+      - IERC721Enumerable
+      - IERC721Full
+      - ERC721Full
+      - IERC721Receiver
+  - title: Extensions
+    contracts:
+      - ERC721Mintable
+      - ERC721MetadataMintable
+      - ERC721Burnable
+      - ERC721Pausable
+  - title: Convenience
+    contracts:
+      - ERC721Holder
+---
+
+This set of interfaces, contracts, and utilities are all related to the [ERC721 Non-Fungible Token Standard](https://eips.ethereum.org/EIPS/eip-721).
+
+*For a walkthrough on how to create an ERC721 token read our [ERC721 guide](../../tokens.md#erc721).*
+
+The EIP consists of three interfaces, found here as `IERC721`,
+`IERC721Metadata`, and `IERC721Enumerable`. Only the first one is required in a
+contract to be ERC721 compliant. Each interface is implemented separately in
+`ERC721`, `ERC721Metadata`, and `ERC721Enumerable`. You can choose the subset
+of functionality you would like to support in your token by combining the
+desired subset through inheritance. The fully featured token implementing all
+three interfaces is prepackaged as `ERC721Full`.
+
+> This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/token/ERC777/ERC777.sol

@@ -9,8 +9,19 @@ import "../../utils/Address.sol";
 import "../../introspection/IERC1820Registry.sol";
 
 /**
- * @title ERC777 token implementation, with granularity harcoded to 1.
- * @author etsvigun <utgarda@gmail.com>, Bertrand Masius <github@catageeks.tk>
+ * @dev Implementation of the `IERC777` interface.
+ *
+ * This implementation is agnostic to the way tokens are created. This means
+ * that a supply mechanism has to be added in a derived contract using `_mint`.
+ *
+ * Support for ERC20 is included in this contract, as specified by the EIP: both
+ * the ERC777 and ERC20 interfaces can be safely used when interacting with it.
+ * Both `IERC777.Sent` and `IERC20.Transfer` events are emitted on token
+ * movements.
+ *
+ * Additionally, the `granularity` value is hard-coded to `1`, meaning that there
+ * are no special restrictions in the amount of tokens that created, moved, or
+ * destroyed. This makes integration with ERC20 applications seamless.
  */
 contract ERC777 is IERC777, IERC20 {
     using SafeMath for uint256;
@@ -49,6 +60,9 @@ contract ERC777 is IERC777, IERC20 {
     // ERC20-allowances
     mapping (address => mapping (address => uint256)) private _allowances;
 
+    /**
+     * @dev `defaultOperators` may be an empty array.
+     */
     constructor(
         string memory name,
         string memory symbol,
@@ -68,107 +82,106 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev Send the amount of tokens from the address msg.sender to the address to
-     * @param to address recipient address
-     * @param amount uint256 amount of tokens to transfer
-     * @param data bytes information attached to the send, and intended for the recipient (to)
+     * @dev See `IERC777.name`.
      */
-    function send(address to, uint256 amount, bytes calldata data) external {
-        _send(msg.sender, msg.sender, to, amount, data, "", true);
+    function name() public view returns (string memory) {
+        return _name;
     }
 
     /**
-     * @dev Send the amount of tokens on behalf of the address from to the address to
-     * @param from address token holder address.
-     * @param to address recipient address
-     * @param amount uint256 amount of tokens to transfer
-     * @param data bytes information attached to the send, and intended for the recipient (to)
-     * @param operatorData bytes extra information provided by the operator (if any)
+     * @dev See `IERC777.symbol`.
      */
-    function operatorSend(
-        address from,
-        address to,
-        uint256 amount,
-        bytes calldata data,
-        bytes calldata operatorData
-    )
-    external
-    {
-        require(isOperatorFor(msg.sender, from), "ERC777: caller is not an operator for holder");
-        _send(msg.sender, from, to, amount, data, operatorData, true);
+    function symbol() public view returns (string memory) {
+        return _symbol;
     }
 
     /**
-     * @dev Transfer token to a specified address.
-     * Required for ERC20 compatiblity. Note that transferring tokens this way may result in locked tokens (i.e. tokens
-     * can be sent to a contract that does not implement the ERC777TokensRecipient interface).
-     * @param to The address to transfer to.
-     * @param value The amount to be transferred.
+     * @dev See `ERC20Detailed.decimals`.
+     *
+     * Always returns 18, as per the
+     * [ERC777 EIP](https://eips.ethereum.org/EIPS/eip-777#backward-compatibility).
      */
-    function transfer(address to, uint256 value) external returns (bool) {
-        require(to != address(0), "ERC777: transfer to the zero address");
-
-        address from = msg.sender;
+    function decimals() public pure returns (uint8) {
+        return 18;
+    }
 
-        _callTokensToSend(from, from, to, value, "", "");
+    /**
+     * @dev See `IERC777.granularity`.
+     *
+     * This implementation always returns `1`.
+     */
+    function granularity() public view returns (uint256) {
+        return 1;
+    }
 
-        _move(from, from, to, value, "", "");
+    /**
+     * @dev See `IERC777.totalSupply`.
+     */
+    function totalSupply() public view returns (uint256) {
+        return _totalSupply;
+    }
 
-        _callTokensReceived(from, from, to, value, "", "", false);
+    /**
+     * @dev Returns the amount of tokens owned by an account (`owner`).
+     */
+    function balanceOf(address tokenHolder) public view returns (uint256) {
+        return _balances[tokenHolder];
+    }
 
-        return true;
+    /**
+     * @dev See `IERC777.send`.
+     *
+     * Also emits a `Transfer` event for ERC20 compatibility.
+     */
+    function send(address recipient, uint256 amount, bytes calldata data) external {
+        _send(msg.sender, msg.sender, recipient, amount, data, "", true);
     }
 
     /**
-     * @dev Transfer tokens from one address to another.
-     * Note that while this function emits an Approval event, this is not required as per the specification,
-     * and other compliant implementations may not emit the event.
-     * Required for ERC20 compatiblity. Note that transferring tokens this way may result in locked tokens (i.e. tokens
-     * can be sent to a contract that does not implement the ERC777TokensRecipient interface).
-     * @param from address The address which you want to send tokens from
-     * @param to address The address which you want to transfer to
-     * @param value uint256 the amount of tokens to be transferred
+     * @dev See `IERC20.transfer`.
+     *
+     * Unlike `send`, `recipient` is _not_ required to implement the `tokensReceived`
+     * interface if it is a contract.
+     *
+     * Also emits a `Sent` event.
      */
-    function transferFrom(address from, address to, uint256 value) external returns (bool) {
-        require(to != address(0), "ERC777: transfer to the zero address");
-        require(from != address(0), "ERC777: transfer from the zero address");
+    function transfer(address recipient, uint256 amount) external returns (bool) {
+        require(recipient != address(0), "ERC777: transfer to the zero address");
 
-        address operator = msg.sender;
+        address from = msg.sender;
 
-        _callTokensToSend(operator, from, to, value, "", "");
+        _callTokensToSend(from, from, recipient, amount, "", "");
 
-        _move(operator, from, to, value, "", "");
-        _approve(from, operator, _allowances[from][operator].sub(value));
+        _move(from, from, recipient, amount, "", "");
 
-        _callTokensReceived(operator, from, to, value, "", "", false);
+        _callTokensReceived(from, from, recipient, amount, "", "", false);
 
         return true;
     }
 
     /**
-     * @dev Burn the amount of tokens from the address msg.sender
-     * @param amount uint256 amount of tokens to transfer
-     * @param data bytes extra information provided by the token holder
+     * @dev See `IERC777.burn`.
+     *
+     * Also emits a `Transfer` event for ERC20 compatibility.
      */
     function burn(uint256 amount, bytes calldata data) external {
         _burn(msg.sender, msg.sender, amount, data, "");
     }
 
     /**
-     * @dev Burn the amount of tokens on behalf of the address from
-     * @param from address token holder address.
-     * @param amount uint256 amount of tokens to transfer
-     * @param data bytes extra information provided by the token holder
-     * @param operatorData bytes extra information provided by the operator (if any)
+     * @dev See `IERC777.isOperatorFor`.
      */
-    function operatorBurn(address from, uint256 amount, bytes calldata data, bytes calldata operatorData) external {
-        require(isOperatorFor(msg.sender, from), "ERC777: caller is not an operator for holder");
-        _burn(msg.sender, from, amount, data, operatorData);
+    function isOperatorFor(
+        address operator,
+        address tokenHolder
+    ) public view returns (bool) {
+        return operator == tokenHolder ||
+            (_defaultOperators[operator] && !_revokedDefaultOperators[tokenHolder][operator]) ||
+            _operators[tokenHolder][operator];
     }
 
     /**
-     * @dev Authorize an operator for the sender
-     * @param operator address to be authorized as operator
+     * @dev See `IERC777.authorizeOperator`.
      */
     function authorizeOperator(address operator) external {
         require(msg.sender != operator, "ERC777: authorizing self as operator");
@@ -183,8 +196,7 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev Revoke operator rights from one of the default operators
-     * @param operator address to revoke operator rights from
+     * @dev See `IERC777.revokeOperator`.
      */
     function revokeOperator(address operator) external {
         require(operator != msg.sender, "ERC777: revoking self as operator");
@@ -199,130 +211,122 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev Approve the passed address to spend the specified amount of tokens on behalf of msg.sender.
-     * Beware that changing an allowance with this method brings the risk that someone may use both the old
-     * and the new allowance by unfortunate transaction ordering. One possible solution to mitigate this
-     * race condition is to first reduce the spender's allowance to 0 and set the desired value afterwards:
-     * https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729
-     * Required for ERC20 compatilibity.
-     * @param spender The address which will spend the funds.
-     * @param value The amount of tokens to be spent.
+     * @dev See `IERC777.defaultOperators`.
      */
-    function approve(address spender, uint256 value) external returns (bool) {
-        _approve(msg.sender, spender, value);
-        return true;
+    function defaultOperators() public view returns (address[] memory) {
+        return _defaultOperatorsArray;
     }
 
     /**
-     * @dev Total number of tokens in existence
+     * @dev See `IERC777.operatorSend`.
+     *
+     * Emits `Sent` and `Transfer` events.
      */
-    function totalSupply() public view returns (uint256) {
-        return _totalSupply;
+    function operatorSend(
+        address sender,
+        address recipient,
+        uint256 amount,
+        bytes calldata data,
+        bytes calldata operatorData
+    )
+    external
+    {
+        require(isOperatorFor(msg.sender, sender), "ERC777: caller is not an operator for holder");
+        _send(msg.sender, sender, recipient, amount, data, operatorData, true);
     }
 
     /**
-     * @dev Gets the balance of the specified address.
-     * @param tokenHolder The address to query the balance of.
-        * @return uint256 representing the amount owned by the specified address.
+     * @dev See `IERC777.operatorBurn`.
+     *
+     * Emits `Sent` and `Transfer` events.
      */
-    function balanceOf(address tokenHolder) public view returns (uint256) {
-        return _balances[tokenHolder];
+    function operatorBurn(address account, uint256 amount, bytes calldata data, bytes calldata operatorData) external {
+        require(isOperatorFor(msg.sender, account), "ERC777: caller is not an operator for holder");
+        _burn(msg.sender, account, amount, data, operatorData);
     }
 
     /**
-     * @return the name of the token.
+     * @dev See `IERC20.allowance`.
+     *
+     * Note that operator and allowance concepts are orthogonal: operators may
+     * not have allowance, and accounts with allowance may not be operators
+     * themselves.
      */
-    function name() public view returns (string memory) {
-        return _name;
+    function allowance(address owner, address spender) public view returns (uint256) {
+        return _allowances[owner][spender];
     }
 
     /**
-     * @return the symbol of the token.
+     * @dev See `IERC20.approve`.
+     *
+     * Note that accounts cannot have allowance issued by their operators.
      */
-    function symbol() public view returns (string memory) {
-        return _symbol;
+    function approve(address spender, uint256 value) external returns (bool) {
+        _approve(msg.sender, spender, value);
+        return true;
     }
 
-    /**
-     * @return the number of decimals of the token.
-     */
-    function decimals() public pure returns (uint8) {
-        return 18; // The spec requires that decimals be 18
-    }
+   /**
+    * @dev See `IERC20.transferFrom`.
+    *
+    * Note that operator and allowance concepts are orthogonal: operators cannot
+    * call `transferFrom` (unless they have allowance), and accounts with
+    * allowance cannot call `operatorSend` (unless they are operators).
+    *
+    * Emits `Sent` and `Transfer` events.
+    */
+    function transferFrom(address sender, address recipient, uint256 amount) external returns (bool) {
+        require(recipient != address(0), "ERC777: transfer to the zero address");
+        require(sender != address(0), "ERC777: transfer from the zero address");
 
-    /**
-     * @dev Gets the token's granularity,
-     * i.e. the smallest number of tokens (in the basic unit)
-     * which may be minted, sent or burned at any time
-     * @return uint256 granularity
-     */
-    function granularity() public view returns (uint256) {
-        return 1;
-    }
+        address operator = msg.sender;
 
-    /**
-     * @dev Get the list of default operators as defined by the token contract.
-     * @return address[] default operators
-     */
-    function defaultOperators() public view returns (address[] memory) {
-        return _defaultOperatorsArray;
-    }
+        _callTokensToSend(operator, sender, recipient, amount, "", "");
 
-    /**
-     * @dev Indicate whether an address
-     * is an operator of the tokenHolder address
-     * @param operator address which may be an operator of tokenHolder
-     * @param tokenHolder address of a token holder which may have the operator
-     * address as an operator.
-     */
-    function isOperatorFor(
-        address operator,
-        address tokenHolder
-    ) public view returns (bool) {
-        return operator == tokenHolder ||
-            (_defaultOperators[operator] && !_revokedDefaultOperators[tokenHolder][operator]) ||
-            _operators[tokenHolder][operator];
-    }
+        _move(operator, sender, recipient, amount, "", "");
+        _approve(sender, operator, _allowances[sender][operator].sub(amount));
 
-    /**
-     * @dev Function to check the amount of tokens that an owner allowed to a spender.
-     * Required for ERC20 compatibility.
-     * @param owner address The address which owns the funds.
-     * @param spender address The address which will spend the funds.
-     * @return A uint256 specifying the amount of tokens still available for the spender.
-     */
-    function allowance(address owner, address spender) public view returns (uint256) {
-        return _allowances[owner][spender];
+        _callTokensReceived(operator, sender, recipient, amount, "", "", false);
+
+        return true;
     }
 
     /**
-     * @dev Mint tokens. Does not check authorization of operator
-     * @dev the caller may ckeck that operator is authorized before calling
-     * @param operator address operator requesting the operation
-     * @param to address token recipient address
-     * @param amount uint256 amount of tokens to mint
-     * @param userData bytes extra information defined by the token recipient (if any)
-     * @param operatorData bytes extra information provided by the operator (if any)
+     * @dev Creates `amount` tokens and assigns them to `account`, increasing
+     * the total supply.
+     *
+     * If a send hook is registered for `raccount`, the corresponding function
+     * will be called with `operator`, `data` and `operatorData`.
+     *
+     * See `IERC777Sender` and `IERC777Recipient`.
+     *
+     * Emits `Sent` and `Transfer` events.
+     *
+     * Requirements
+     *
+     * - `account` cannot be the zero address.
+     * - if `account` is a contract, it must implement the `tokensReceived`
+     * interface.
      */
     function _mint(
         address operator,
-        address to,
+        address account,
         uint256 amount,
         bytes memory userData,
         bytes memory operatorData
     )
     internal
     {
-        require(to != address(0), "ERC777: mint to the zero address");
+        require(account != address(0), "ERC777: mint to the zero address");
 
         // Update state variables
         _totalSupply = _totalSupply.add(amount);
-        _balances[to] = _balances[to].add(amount);
+        _balances[account] = _balances[account].add(amount);
 
-        _callTokensReceived(operator, address(0), to, amount, userData, operatorData, true);
+        _callTokensReceived(operator, address(0), account, amount, userData, operatorData, true);
 
-        emit Minted(operator, to, amount, userData, operatorData);
-        emit Transfer(address(0), to, amount);
+        emit Minted(operator, account, amount, userData, operatorData);
+        emit Transfer(address(0), account, amount);
     }
 
     /**

contracts/token/ERC777/IERC777.sol

@@ -1,47 +1,172 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title ERC777 token interface
- * @dev See https://eips.ethereum.org/EIPS/eip-777
+ * @dev Interface of the ERC777Token standard as defined in the EIP.
+ *
+ * This contract uses the
+ * [ERC1820 registry standard](https://eips.ethereum.org/EIPS/eip-1820) to let
+ * token holders and recipients react to token movements by using setting implementers
+ * for the associated interfaces in said registry. See `IERC1820Registry` and
+ * `ERC1820Implementer`.
  */
 interface IERC777 {
+    /**
+     * @dev Returns the name of the token.
+     */
+    function name() external view returns (string memory);
+
+    /**
+     * @dev Returns the symbol of the token, usually a shorter version of the
+     * name.
+     */
+    function symbol() external view returns (string memory);
+
+    /**
+     * @dev Returns the smallest part of the token that is not divisible. This
+     * means all token operations (creation, movement and destruction) must have
+     * amounts that are a multiple of this number.
+     *
+     * For most token contracts, this value will equal 1.
+     */
+    function granularity() external view returns (uint256);
+
+    /**
+     * @dev Returns the amount of tokens in existence.
+     */
+    function totalSupply() external view returns (uint256);
+
+    /**
+     * @dev Returns the amount of tokens owned by an account (`owner`).
+     */
+    function balanceOf(address owner) external view returns (uint256);
+
+    /**
+     * @dev Moves `amount` tokens from the caller's account to `recipient`.
+     *
+     * If send or receive hooks are registered for the caller and `recipient`,
+     * the corresponding functions will be called with `data` and empty
+     * `operatorData`. See `IERC777Sender` and `IERC777Recipient`.
+     *
+     * Emits a `Sent` event.
+     *
+     * Requirements
+     *
+     * - the caller must have at least `amount` tokens.
+     * - `recipient` cannot be the zero address.
+     * - if `recipient` is a contract, it must implement the `tokensReceived`
+     * interface.
+     */
+    function send(address recipient, uint256 amount, bytes calldata data) external;
+
+    /**
+     * @dev Destoys `amount` tokens from the caller's account, reducing the
+     * total supply.
+     *
+     * If a send hook is registered for the caller, the corresponding function
+     * will be called with `data` and empty `operatorData`. See `IERC777Sender`.
+     *
+     * Emits a `Burned` event.
+     *
+     * Requirements
+     *
+     * - the caller must have at least `amount` tokens.
+     */
+    function burn(uint256 amount, bytes calldata data) external;
+
+    /**
+     * @dev Returns true if an account is an operator of `tokenHolder`.
+     * Operators can send and burn tokens on behalf of their owners. All
+     * accounts are their own operator.
+     *
+     * See `operatorSend` and `operatorBurn`.
+     */
+    function isOperatorFor(address operator, address tokenHolder) external view returns (bool);
+
+    /**
+     * @dev Make an account an operator of the caller.
+     *
+     * See `isOperatorFor`.
+     *
+     * Emits an `AuthorizedOperator` event.
+     *
+     * Requirements
+     *
+     * - `operator` cannot be calling address.
+     */
     function authorizeOperator(address operator) external;
 
+    /**
+     * @dev Make an account an operator of the caller.
+     *
+     * See `isOperatorFor` and `defaultOperators`.
+     *
+     * Emits a `RevokedOperator` event.
+     *
+     * Requirements
+     *
+     * - `operator` cannot be calling address.
+     */
     function revokeOperator(address operator) external;
 
-    function send(address to, uint256 amount, bytes calldata data) external;
+    /**
+     * @dev Returns the list of default operators. These accounts are operators
+     * for all token holders, even if `authorizeOperator` was never called on
+     * them.
+     *
+     * This list is immutable, but individual holders may revoke these via
+     *`revokeOperator`, in which case `isOperatorFor` will return false.
+     */
+    function defaultOperators() external view returns (address[] memory);
 
+    /**
+     * @dev Moves `amount` tokens from `sender` to `recipient`. The caller must
+     * be an operator of `sender`.
+     *
+     * If send or receive hooks are registered for `sender` and `recipient`,
+     * the corresponding functions will be called with `data` and
+     * `operatorData`. See `IERC777Sender` and `IERC777Recipient`.
+     *
+     * Emits a `Sent` event.
+     *
+     * Requirements
+     *
+     * - `sender` cannot be the zero address.
+     * - `sender` must have at least `amount` tokens.
+     * - the caller must be an operator for `sender`.
+     * - `recipient` cannot be the zero address.
+     * - if `recipient` is a contract, it must implement the `tokensReceived`
+     * interface.
+     */
     function operatorSend(
-        address from,
-        address to,
+        address sender,
+        address recipient,
         uint256 amount,
         bytes calldata data,
         bytes calldata operatorData
     ) external;
 
-    function burn(uint256 amount, bytes calldata data) external;
-
+    /**
+     * @dev Destoys `amount` tokens from `account`, reducing the total supply.
+     * The caller must be an operator of `account`.
+     *
+     * If a send hook is registered for `account`, the corresponding function
+     * will be called with `data` and `operatorData`. See `IERC777Sender`.
+     *
+     * Emits a `Burned` event.
+     *
+     * Requirements
+     *
+     * - `account` cannot be the zero address.
+     * - `account` must have at least `amount` tokens.
+     * - the caller must be an operator for `account`.
+     */
     function operatorBurn(
-        address from,
+        address account,
         uint256 amount,
         bytes calldata data,
         bytes calldata operatorData
     ) external;
 
-    function name() external view returns (string memory);
-
-    function symbol() external view returns (string memory);
-
-    function totalSupply() external view returns (uint256);
-
-    function balanceOf(address owner) external view returns (uint256);
-
-    function granularity() external view returns (uint256);
-
-    function defaultOperators() external view returns (address[] memory);
-
-    function isOperatorFor(address operator, address tokenHolder) external view returns (bool);
-
     event Sent(
         address indexed operator,
         address indexed from,

contracts/token/ERC777/IERC777Recipient.sol

@@ -1,10 +1,26 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title ERC777 token recipient interface
- * @dev See https://eips.ethereum.org/EIPS/eip-777
+ * @dev Interface of the ERC777TokensRecipient standard as defined in the EIP.
+ *
+ * Accounts can be notified of `IERC777` tokens being sent to them by having a
+ * contract implement this interface (contract holders can be their own
+ * implementer) and registering it on the
+ * [ERC1820 global registry](https://eips.ethereum.org/EIPS/eip-1820).
+ *
+ * See `IERC1820Registry` and `ERC1820Implementer`.
  */
-interface IERC777Recipient {
+ interface IERC777Recipient {
+    /**
+     * @dev Called by an `IERC777` token contract whenever tokens are being
+     * moved or created into a registered account (`to`). The type of operation
+     * is conveyed by `from` being the zero address or not.
+     *
+     * This call occurs _after_ the token contract's state is updated, so
+     * `IERC777.balanceOf`, etc., can be used to query the post-operation state.
+     *
+     * This function may revert to prevent the operation from being executed.
+     */
     function tokensReceived(
         address operator,
         address from,

contracts/token/ERC777/IERC777Sender.sol

@@ -1,10 +1,26 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title ERC777 token sender interface
- * @dev See https://eips.ethereum.org/EIPS/eip-777
+ * @dev Interface of the ERC777TokensSender standard as defined in the EIP.
+ *
+ * `IERC777` Token holders can be notified of operations performed on their
+ * tokens by having a contract implement this interface (contract holders can be
+ *  their own implementer) and registering it on the
+ * [ERC1820 global registry](https://eips.ethereum.org/EIPS/eip-1820).
+ *
+ * See `IERC1820Registry` and `ERC1820Implementer`.
  */
 interface IERC777Sender {
+    /**
+     * @dev Called by an `IERC777` token contract whenever a registered holder's
+     * (`from`) tokens are about to be moved or destroyed. The type of operation
+     * is conveyed by `to` being the zero address or not.
+     *
+     * This call occurs _before_ the token contract's state is updated, so
+     * `IERC777.balanceOf`, etc., can be used to query the pre-operation state.
+     *
+     * This function may revert to prevent the operation from being executed.
+     */
     function tokensToSend(
         address operator,
         address from,

contracts/token/ERC777/README.md

@@ -0,0 +1,17 @@
+---
+sections:
+  - title: Core
+    contracts:
+      - IERC777
+      - ERC777
+  - title: Hooks
+    contracts:
+      - IERC777Sender
+      - IERC777Recipient
+---
+
+This set of interfaces and contracts are all related to the [ERC777 token standard](https://eips.ethereum.org/EIPS/eip-777).
+
+The token behavior itself is implemented in the core contracts: `IERC777`, `ERC777`.
+
+Additionally there are interfaces used to develop contracts that react to token movements: `IERC777Sender`, `IERC777Recipient`.

contracts/utils/Address.sol

@@ -1,24 +1,25 @@
 pragma solidity ^0.5.0;
 
 /**
- * Utility library of inline functions on addresses
+ * @dev Collection of functions related to the address type,
  */
 library Address {
     /**
-     * Returns whether the target address is a contract
-     * @dev This function will return false if invoked during the constructor of a contract,
-     * as the code is not actually created until after the constructor finishes.
-     * @param account address of the account to check
-     * @return whether the target address is a contract
+     * @dev Returns true if `account` is a contract.
+     *
+     * This test is non-exhaustive, and there may be false-negatives: during the
+     * execution of a contract's constructor, its address will be reported as
+     * not containing a contract.
+     *
+     * > It is unsafe to assume that an address for which this function returns
+     * false is an externally-owned account (EOA) and not a contract.
      */
     function isContract(address account) internal view returns (bool) {
+        // This method relies in extcodesize, which returns 0 for contracts in
+        // construction, since the code is only stored at the end of the
+        // constructor execution.
+
         uint256 size;
-        // XXX Currently there is no better way to check if there is a contract in an address
-        // than to check the size of the code at that address.
-        // See https://ethereum.stackexchange.com/a/14016/36603
-        // for more details about how this works.
-        // TODO Check this again before the Serenity release, because all addresses will be
-        // contracts then.
         // solhint-disable-next-line no-inline-assembly
         assembly { size := extcodesize(account) }
         return size > 0;

contracts/utils/Arrays.sol

@@ -2,21 +2,18 @@ pragma solidity ^0.5.0;
 
 import "../math/Math.sol";
 
-
 /**
- * @title Arrays
- * @dev Utility library of inline array functions
+ * @dev Collection of functions related to array types.
  */
 library Arrays {
-    /**
-     * @dev Upper bound search function which is kind of binary search algorithm. It searches sorted
-     * array to find index of the element value. If element is found then returns its index otherwise
-     * it returns index of first element which is greater than searched value. If searched element is
-     * bigger than any array element function then returns first index after last element (i.e. all
-     * values inside the array are smaller than the target). Complexity O(log n).
-     * @param array The array sorted in ascending order.
-     * @param element The element's value to be found.
-     * @return The calculated index value. Returns 0 for empty array.
+   /**
+     * @dev Searches a sorted `array` and returns the first index that contains
+     * a value greater or equal to `element`. If no such index exists (i.e. all
+     * values in the array are stictly less than `element`), the array length is
+     * returned. Time complexity O(log n).
+     *
+     * `array` is expected to be sorted in ascending order, and to contain no
+     * repeated elements.
      */
     function findUpperBound(uint256[] storage array, uint256 element) internal view returns (uint256) {
         if (array.length == 0) {

contracts/utils/README.md

@@ -0,0 +1,11 @@
+---
+title: Utilities
+sections:
+  - title: Contracts
+    contracts:
+      - Address
+      - Arrays
+      - ReentrancyGuard
+---
+
+Miscellaneous contracts containing utility functions, often related to working with different data types.

contracts/utils/ReentrancyGuard.sol

@@ -1,10 +1,16 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title Helps contracts guard against reentrancy attacks.
- * @author Remco Bloemen <remco@2π.com>, Eenae <alexey@mixbytes.io>
- * @dev If you mark a function `nonReentrant`, you should also
- * mark it `external`.
+ * @dev Contract module that helps prevent reentrant calls to a function.
+ *
+ * Inheriting from `ReentrancyGuard` will make the `nonReentrant` modifier
+ * available, which can be aplied to functions to make sure there are no nested
+ * (reentrant) calls to them.
+ *
+ * Note that because there is a single `nonReentrant` guard, functions marked as
+ * `nonReentrant` may not call one another. This can be worked around by making
+ * those functions `private`, and then adding `external` `nonReentrant` entry
+ * points to them.
  */
 contract ReentrancyGuard {
     /// @dev counter to allow mutex lock with only one SSTORE operation

docs/learn-about-access-control.md → docs/access-control.md

@@ -1,6 +1,6 @@
 ---
-id: learn-about-access-control
-title: Learn About Access Control
+id: access-control
+title: Access Control
 ---
 
 Access control—that is, "who is allowed to do this thing"—is incredibly important in the world of smart contracts. The access control of your contract governs who can mint tokens, who can vote on proposals, who can [`selfdestruct()`](https://blog.zeppelin.solutions/on-the-parity-wallet-multisig-hack-405a8c12e8f7) the contract, and more, so it's very important to understand how you implement it.
@@ -9,7 +9,7 @@ Access control—that is, "who is allowed to do this thing"—is incredibly impo
 
 The most common and basic form of access control is the concept of _ownership_: there's one account that is the `owner` and can do administrative tasks on contracts. This approach is perfectly reasonable for contracts that only have a single administrative user.
 
-OpenZeppelin provides [contracts/ownership/Ownable.sol](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/ownership/Ownable.sol) for implementing ownership in your contracts.
+OpenZeppelin provides [`Ownable`](api/ownership#ownable) for implementing ownership in your contracts.
 
 ```solidity
 import "openzeppelin-solidity/contracts/ownership/Ownable.sol";
@@ -31,11 +31,11 @@ contract MyContract is Ownable {
 }
 ```
 
-By default, the `owner` of an `Ownable` contract is the `msg.sender` of the contract creation transaction, which is usually exactly what you want.
+By default, the [`owner`](api/ownership#Ownable.owner()) of an `Ownable` contract is the `msg.sender` of the contract creation transaction, which is usually exactly what you want.
 
 Ownable also lets you:
-+ `transferOwnership(address newOwner)` to transfer ownership from one account to another
-+ `renounceOwnership()` to remove the owner altogether, useful for decentralizing control of your contract. **⚠ Warning!** Removing the owner altogether will mean that administrative tasks that are protected by `onlyOwner` will no longer be callable!
++ [`transferOwnership`](api/ownership#Ownable.transferOwnership(address)) to transfer ownership from one account to another
++ [`renounceOwnership`](api/ownership#Ownable.renounceOwnership()) to remove the owner altogether, useful for decentralizing control of your contract. **⚠ Warning!** Removing the owner altogether will mean that administrative tasks that are protected by `onlyOwner` will no longer be callable!
 
 
 Note that any contract that supports sending transactions can also be the owner of a contract; the only requirement is that the owner has an Ethereum address, so it could be a Gnosis Multisig or Gnosis Safe, an Aragon DAO, an ERC725/uPort identity contract, or a totally custom contract that _you_ create.
@@ -44,17 +44,17 @@ In this way you can use _composability_ to add additional layers of access contr
 
 ### Examples in OpenZeppelin
 
-You'll notice that none of the OpenZeppelin contracts use Ownable, though! This is because there are more flexible ways of providing access control that are more in-line with our reusable contract philosophy. For most contracts, We'll use `Roles` to govern who can do what. There are some cases, though—like with `Escrow`—where there's a direct relationship between contracts. In those cases, we'll use [`Secondary`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/ownership/Secondary.sol) to create a "secondary" contract that allows a "primary" contract to manage it.
+You'll notice that none of the OpenZeppelin contracts use `Ownable`, though! This is because there are more flexible ways of providing access control that are more in-line with our reusable contract philosophy. For most contracts, We'll use `Roles` to govern who can do what. There are some cases, though—like with [`Escrow`](localhost:3000/api/payment#escrow)—where there's a direct relationship between contracts. In those cases, we'll use [`Secondary`](api/ownership#secondary) to create a "secondary" contract that allows a "primary" contract to manage it.
 
 Let's learn about Role-Based Access Control!
 
-## Role-Based Access Control & Roles.sol
+## Roles & Role-Based Access Control
 
 An alternative to single-concern `Ownable` is role based access control (RBAC), which, instead of keeping track of a single entity with "admin" level privileges, keeps track of multiple different entities with a variety of roles that inform the contract about what they can do.
 
-For example, a `MintableToken` could have a `minter` role that decides who can mint tokens (which could be assigned to a Crowdsale). It could also have a `namer` role that allows changing the name or symbol of the token (for whatever reason). RBAC gives you much more flexibility over who can do what and is generally recommended for applications that need more configurability. If you're experienced with web development, the vast majority of access control systems are role-based: some users are normal users, some are moderators, and some can be company employee admins.
+For example, a [`MintableToken`](api/token/ERC20#erc20mintable) could have a `minter` role that decides who can mint tokens (which could be assigned to a [`Crowdsale`](api/crowdsale#crowdsale)). It could also have a `namer` role that allows changing the name or symbol of the token (for whatever reason). RBAC gives you much more flexibility over who can do what and is generally recommended for applications that need more configurability. If you're experienced with web development, the vast majority of access control systems are role-based: some users are normal users, some are moderators, and some can be company employee admins.
 
-OpenZeppelin provides [contracts/access/Roles.sol](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/access/Roles.sol) for implementing role-based access control.
+OpenZeppelin provides [`Roles`](api/access#roles) for implementing role-based access control.
 
 Here's an example of using `Roles` in our token example above, we'll use it to implement a token that can be minted by `Minters` and renamed by `Namers`:
 

docs/learn-about-crowdsales.md → docs/crowdsales.md

@@ -1,6 +1,6 @@
 ---
-id: learn-about-crowdsales
-title: Learn About Crowdsales
+id: crowdsales
+title: Crowdsales
 ---
 
 Crowdsales are a popular use for Ethereum; they let you allocate tokens to network participants in various ways, mostly in exchange for Ether. They come in a variety of shapes and flavors, so let's go over the various types available in OpenZeppelin and how to use them.
@@ -20,7 +20,7 @@ Crowdsales have a bunch of different properties, but here are some important one
   - Does distribution of funds happen in real-time or after the crowdsale?
   - Can participants receive a refund if the goal is not met?
 
-To manage all of the different combinations and flavors of crowdsales, OpenZeppelin provides a highly configurable [`Crowdsale.sol`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/Crowdsale.sol) base contract that can be combined with various other functionalities to construct a bespoke crowdsale.
+To manage all of the different combinations and flavors of crowdsales, OpenZeppelin provides a highly configurable [`Crowdsale`](api/crowdsale#crowdsale) base contract that can be combined with various other functionalities to construct a bespoke crowdsale.
 
 ## Crowdsale Rate
 
@@ -60,9 +60,9 @@ One more for practice: if I want to issue "1 TKN for every dollar (USD) in Ether
 
 One of the first decisions you have to make is "how do I get these tokens to users?". This is usually done in one of three ways:
 
-- (default) — The Crowdsale contract owns tokens and simply transfers tokens from its own ownership to users that purchase them.
-- [MintedCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/emission/MintedCrowdsale.sol) — The Crowdsale mints tokens when a purchase is made.
-- [AllowanceCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/emission/AllowanceCrowdsale.sol) — The Crowdsale is granted an allowance to another wallet (like a Multisig) that already owns the tokens to be sold in the crowdsale.
+- (default) — The `Crowdsale` contract owns tokens and simply transfers tokens from its own ownership to users that purchase them.
+- [`MintedCrowdsale`](api/crowdsale#mintedcrowdsale) — The `Crowdsale` mints tokens when a purchase is made.
+- [`AllowanceCrowdsale`](api/crowdsale#allowancecrowdsale) — The `Crowdsale` is granted an allowance to another wallet (like a Multisig) that already owns the tokens to be sold in the crowdsale.
 
 ### Default Emission
 
@@ -84,7 +84,7 @@ new Crowdsale(
 
 ### Minted Crowdsale
 
-To use a `MintedCrowdsale`, your token must also be a `ERC20Mintable` token that the crowdsale has permission to mint from. This can look like:
+To use a [`MintedCrowdsale`](api/crowdsale#mintedcrowdsale), your token must also be a [`ERC20Mintable`](api/token/ERC20#erc20mintable) token that the crowdsale has permission to mint from. This can look like:
 
 ```solidity
 contract MyToken is ERC20, ERC20Mintable {
@@ -128,7 +128,7 @@ contract MyCrowdsaleDeployer {
 
 ### AllowanceCrowdsale
 
-Use an `AllowanceCrowdsale` to send tokens from another wallet to the participants of the crowdsale. In order for this to work, the source wallet must give the crowdsale an allowance via the ERC20 `approve(...)` method.
+Use an [`AllowanceCrowdsale`](api/crowdsale#allowancecrowdsale) to send tokens from another wallet to the participants of the crowdsale. In order for this to work, the source wallet must give the crowdsale an allowance via the ERC20 [`approve`](api/token/ERC20#IERC20.approve(address,uint256)) method.
 
 ```solidity
 contract MyCrowdsale is AllowanceCrowdsale, Crowdsale {
@@ -157,10 +157,10 @@ IERC20(tokenAddress).approve(CROWDALE_ADDRESS, SOME_TOKEN_AMOUNT);
 
 There are a bunch of different validation requirements that your crowdsale might be a part of:
 
-- [CappedCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/validation/CappedCrowdsale.sol) — adds a cap to your crowdsale, invalidating any purchases that would exceed that cap
-- [IndividuallyCappedCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/validation/IndividuallyCappedCrowdsale.sol) — caps an individual's contributions.
-- [WhitelistedCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/validation/WhitelistedCrowdsale.sol) — only allow whitelisted participants to purchase tokens. this is useful for putting your KYC / AML whitelist on-chain!
-- [TimedCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/validation/TimedCrowdsale.sol) — adds an `openingTime` and `closingTime` to your crowdsale
+- [`CappedCrowdsale`](api/crowdsale#cappedcrowdsale) — adds a cap to your crowdsale, invalidating any purchases that would exceed that cap
+- [`IndividuallyCappedCrowdsale`](api/crowdsale#individuallycappedcrowdsale) — caps an individual's contributions.
+- [`WhitelistCrowdsale`](api/crowdsale#whitelistcrowdsale) — only allow whitelisted participants to purchase tokens. this is useful for putting your KYC / AML whitelist on-chain!
+- [`TimedCrowdsale`](api/crowdsale#timedcrowdsale) — adds an [`openingTime`](api/crowdsale#TimedCrowdsale.openingTime()) and [`closingTime`](api/crowdsale#TimedCrowdsale.closingTime()) to your crowdsale
 
 Simply mix and match these crowdsale flavors to your heart's content:
 
@@ -197,7 +197,7 @@ OpenZeppelin is here to make that easy!
 
 ### PostDeliveryCrowdsale
 
-The [PostDeliveryCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/distribution/PostDeliveryCrowdsale.sol), as its name implies, distributes tokens after the crowdsale has finished, letting users call `withdrawTokens()` in order to claim the tokens they've purchased.
+The [`PostDeliveryCrowdsale`](api/crowdsale#postdeliverycrowdsale), as its name implies, distributes tokens after the crowdsale has finished, letting users call [`withdrawTokens`](api/crowdsale#PostDeliveryCrowdsale.withdrawTokens(address)) in order to claim the tokens they've purchased.
 
 ```solidity
 contract MyCrowdsale is PostDeliveryCrowdsale, TimedCrowdsale, Crowdsale {
@@ -222,7 +222,7 @@ contract MyCrowdsale is PostDeliveryCrowdsale, TimedCrowdsale, Crowdsale {
 
 ### RefundableCrowdsale
 
-The [RefundableCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/distribution/RefundableCrowdsale.sol) offers to refund users if a minimum goal is not reached. If the goal is not reached, the users can `claimRefund()` to get their Ether back.
+The [`RefundableCrowdsale`](api/crowdsale#refundablecrowdsale) offers to refund users if a minimum goal is not reached. If the goal is not reached, the users can [`claimRefund`](api/crowdsale#RefundableCrowdsale.claimRefund(address%20payable)) to get their Ether back.
 
 
 ```solidity

docs/get-started.md

@@ -3,7 +3,7 @@ id: get-started
 title: Get Started
 ---
 
-OpenZeppelin can be installed directly into your existing node.js project with `npm install openzeppelin-solidity`. We will use [Truffle](https://github.com/ConsenSys/truffle), an Ethereum development environment, to get started.
+OpenZeppelin can be installed directly into your existing node.js project with `npm install openzeppelin-solidity`. We will use [Truffle](https://github.com/trufflesuite/truffle), an Ethereum development environment, to get started.
 
 Please install Truffle and initialize your project:
 
@@ -33,10 +33,10 @@ contract MyContract is Ownable {
 
 After installing OpenZeppelin, check out the rest of the guides in the sidebar to learn about the different contracts that OpenZeppelin provides and how to use them.
 
-- [Learn About Access Control](learn-about-access-control)
-- [Learn About Crowdsales](learn-about-crowdsales)
-- [Learn About Tokens](learn-about-tokens)
-- [Learn About Utilities](learn-about-utilities)
+- [Learn About Access Control](access-control)
+- [Learn About Crowdsales](crowdsales)
+- [Learn About Tokens](tokens)
+- [Learn About Utilities](utilities)
 
 You may also want to take a look at the guides on our blog, which cover several common use cases and good practices: https://blog.zeppelin.solutions/guides/home.
 

docs/learn-about-utilities.md

@@ -1,94 +0,0 @@
----
-id: learn-about-utilities
-title: Learn About Utilities
----
-
-OpenZeppelin provides a ton of useful utilities that you can use in your project. Here are some of the more popular ones:
-
-## Cryptography
-
-- [ECDSA.sol](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/cryptography/ECDSA.sol) — provides functions for recovering and managing Ethereum account ECDSA signatures:
-  - to use it, declare: `using ECDSA for bytes32;`
-  - signatures are tightly packed, 65 byte `bytes` that look like `{v (1)} {r (32)} {s (32)}`
-    - this is the default from `web3.eth.sign` so you probably don't need to worry about this format
-  - recover the signer using `myDataHash.recover(signature)`
-  - if you are using `eth_personalSign`, the signer will hash your data and then add the prefix `\x19Ethereum Signed Message:\n`, so if you're attempting to recover the signer of an Ethereum signed message hash, you'll want to use `toEthSignedMessageHash`
-
-
-Use these functions in combination to verify that a user has signed some information on-chain:
-
-```solidity
-keccack256(
-    abi.encodePacked(
-        someData,
-        moreData
-    )
-)
-.toEthSignedMessageHash()
-.recover(signature)
-```
-
-- [MerkleProof.sol](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/cryptography/MerkleProof.sol) — provides `verify(...)` for verifying merkle proofs.
-
-
-## Introspection
-
-In Solidity, it's frequently helpful to know whether or not a contract supports an interface you'd like to use. ERC165 is a standard that helps do runtime interface detection. OpenZeppelin provides some helpers, both for implementing ERC165 in your contracts and querying other contracts:
-
-- [IERC165](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/introspection/IERC165.sol) — this is the ERC165 interface that defines `supportsInterface(...)`. When implementing ERC165, you'll conform to this interface.
-- [ERC165](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/introspection/ERC165.sol) — inherit this contract if you'd like to support interface detection using a lookup table in contract storage. You can register interfaces using `_registerInterface(bytes4)`: check out example usage as part of the ERC721 implementation.
-- [ERC165Checker](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/introspection/ERC165Checker.sol) — ERC165Checker simplifies the process of checking whether or not a contract supports an interface you care about.
-  - include with `using ERC165Checker for address;`
-  - `myAddress.supportsInterface(bytes4)`
-  - `myAddress.supportsInterfaces(bytes4[])`
-
-
-```solidity
-contract MyContract {
-    using ERC165Checker for address;
-
-    bytes4 private InterfaceId_ERC721 = 0x80ac58cd;
-
-    /**
-     * @dev transfer an ERC721 token from this contract to someone else
-     */
-    function transferERC721(
-        address token,
-        address to,
-        uint256 tokenId
-    )
-        public
-    {
-        require(token.supportsInterface(InterfaceId_ERC721), "IS_NOT_721_TOKEN");
-        IERC721(token).transferFrom(address(this), to, tokenId);
-    }
-}
-```
-
-## Math
-
-The most popular math related library OpenZeppelin provides is [SafeMath](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/math/SafeMath.sol), which provides mathematical functions that protect your contract from overflows and underflows.
-
-Include the contract with `using SafeMath for uint256;` and then call the functions:
-
-- `myNumber.add(otherNumber)`
-- `myNumber.sub(otherNumber)`
-- `myNumber.div(otherNumber)`
-- `myNumber.mul(otherNumber)`
-- `myNumber.mod(otherNumber)`
-
-Easy!
-
-## Payment
-
-Want to split some payments between multiple people? Maybe you have an app that sends 30% of art purchases to the original creator and 70% of the profits to the current owner; you can build that with [`PaymentSplitter`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/payment/PaymentSplitter.sol)!.
-
-In solidity, there are some security concerns with blindly sending money to accounts, since it allows them to execute arbitrary code. You can read up on these security concerns in the [Ethereum Smart Contract Best Practices](https://consensys.github.io/smart-contract-best-practices/) website. One of the ways to fix reentrancy and stalling problems is, instead of immediately sending Ether to accounts that need it, you can use [`PullPayment`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/payment/PullPayment.sol), which offers an `asyncSend` function for sending money to something and requesting that they `withdraw()` it later.
-
-If you want to Escrow some funds, check out [`Escrow`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/payment/escrow/Escrow.sol) and [`ConditionalEscrow`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/payment/escrow/ConditionalEscrow.sol) for governing the release of some escrowed Ether.
-
-### Misc
-
-Want to check if an address is a contract? Use [`Address`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/utils/Address.sol) and `Address#isContract()`.
-
-Want to keep track of some numbers that increment by 1 every time you want another one? Check out [`Counter`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/v2.1.2/contracts/drafts/Counter.sol). This is especially useful for creating incremental ERC721 tokenIds like we did in the last section.

docs/sidebar.json

@@ -3,10 +3,10 @@
     "get-started"
   ],
   "Guides": [
-    "learn-about-access-control",
-    "learn-about-crowdsales",
-    "learn-about-tokens",
-    "learn-about-utilities"
+    "access-control",
+    "crowdsales",
+    "tokens",
+    "utilities"
   ],
   "API Reference": [
     {

docs/learn-about-tokens.md → docs/tokens.md

@@ -1,6 +1,6 @@
 ---
-id: learn-about-tokens
-title: Learn About Tokens
+id: tokens
+title: Tokens
 ---
 
 Ah, the "token": the world's most powerful and most misused tool. In this section we'll learn to harness the power of native units of account for good and world peace!
@@ -21,22 +21,22 @@ An ERC20 token is a contract that keeps track of a `mapping(address => uint256)`
 
 OpenZeppelin provides a few different ERC20-related contracts. Here are the core contracts you'll almost definitely be using:
 
-- [IERC20](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/IERC20.sol) — defines the interface that all ERC20 token implementations should conform to
-- [ERC20](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/ERC20.sol) — the base implementation of the ERC20 interface
-- [ERC20Detailed](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/ERC20Detailed.sol) — the `name()`, `symbol()`, and `decimals()` getters are optional in the original standard, so `ERC20Detailed` adds that information to your token.
+- [`IERC20`](api/token/ERC20#ierc20) — defines the interface that all ERC20 token implementations should conform to
+- [`ERC20`](api/token/ERC20#erc20) — the base implementation of the ERC20 interface
+- [`ERC20Detailed`](api/token/ERC20#erc20detailed) — the [`name()`](api/token/ERC20#ERC20Detailed.name()), [`symbol()`](api/token/ERC20#ERC20Detailed.symbol()), and [`decimals()`](api/token/ERC20#ERC20Detailed.decimals()) getters are optional in the original standard, so `ERC20Detailed` adds that information to your token.
 
 
 After that, OpenZeppelin provides a few extra properties that you may want depending on your use-case:
 
-- [ERC20Mintable](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/ERC20Mintable.sol) — `ERC20Mintable` allows users with the [`MinterRole`](/api/docs/learn-about-access-control.html) to call the `mint()` function and mint tokens to users. Minting can also be finished, locking the `mint()` function's behavior.
-- [ERC20Burnable](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/ERC20Burnable.sol) — if your token can be burned (aka, it can be destroyed), include this one
-- [ERC20Capped](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/ERC20Capped.sol) — `ERC20Capped` is a type of `ERC20Mintable` that enforces a maximum cap on tokens; this is really useful if you want to ensure network participants that there will always be a maximum number of tokens, and is useful for making sure that multiple different minting methods don't accidentally create more tokens than you expected.
-- [ERC20Pausable](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/ERC20Pausable.sol) — `ERC20Pausable` allows anyone with the Pauser role to pause the token, freezing transfers to and from users. This is useful if you want to stop trades until the end of a crowdsale, or if you want to have an emergency switch for freezing your tokens in the event of a large bug. Note that there are inherent decentralization tradeoffs when using a pausable token; users may not expect that their unstoppable money can be frozen by a single address!
+- [`ERC20Mintable`](api/token/ERC20#erc20mintable) — `ERC20Mintable` allows users with the [`MinterRole`](access-control) to call the [`mint()`](api/token/ERC20#ERC20Mintable.mint(address,uint256)) function and mint tokens to users.
+- [`ERC20Burnable`](api/token/ERC20#erc20burnable) — if your token can be burned (aka, it can be destroyed), include this one.
+- [`ERC20Capped`](api/token/ERC20#erc20capped) — `ERC20Capped` is a type of `ERC20Mintable` that enforces a maximum cap on tokens; this is really useful if you want to ensure network participants that there will always be a maximum number of tokens, and is useful for making sure that multiple different minting methods don't accidentally create more tokens than you expected.
+- [`ERC20Pausable`](api/token/ERC20#erc20pausable) — `ERC20Pausable` allows anyone with the Pauser role to pause the token, freezing transfers to and from users. This is useful if you want to stop trades until the end of a crowdsale, or if you want to have an emergency switch for freezing your tokens in the event of a large bug. Note that there are inherent decentralization tradeoffs when using a pausable token; users may not expect that their unstoppable money can be frozen by a single address!
 
 Finally, if you're working with ERC20 tokens, OpenZeppelin provides some utility contracts:
 
-- [SafeERC20](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/SafeERC20.sol) — provides `safeTransfer`, `safeTransferFrom`, and `safeApprove` that are helpful wrappers around the normal ERC20 functions. Using `SafeERC20` forces transfers and approvals to succeed, or the entire transaction is reverted.
-- [TokenTimelock](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/TokenTimelock.sol) — is an escrow contract for ERC20 tokens that will release some tokens after a specified timeout. This is useful for simple vesting schedules like "advisors get all of their tokens after 1 year". For a better vesting schedule, though, see [`TokenVesting`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/drafts/TokenVesting.sol)
+- [`SafeERC20`](api/token/ERC20#safeerc20) — provides [`safeTransfer`](api/token/ERC20#SafeERC20.safeTransfer(contract%20IERC20,address,uint256)), [`safeTransferFrom`](api/token/ERC20#SafeERC20.safeTransferFrom(contract%20IERC20,address,address,uint256)), and [`safeApprove`](api/token/ERC20#SafeERC20.safeApprove(contract%20IERC20,address,uint256)) that are helpful wrappers around the normal ERC20 functions. Using `SafeERC20` forces transfers and approvals to succeed, or the entire transaction is reverted.
+- [`TokenTimelock`](api/token/ERC20#tokentimelock) — is an escrow contract for ERC20 tokens that will release some tokens after a specified timeout. This is useful for simple vesting schedules like "advisors get all of their tokens after 1 year". For a better vesting schedule, though, see [`TokenVesting`](api/drafts#tokenvesting)
 
 ### Constructing a Nice ERC20 Token
 
@@ -79,11 +79,11 @@ We've discussed how you can make a _fungible_ token using ERC20, but what if not
 
 Let's see what contracts OpenZeppelin provides for helping us work with ERC721:
 
-- The `IERC721`, `IERC721Metadata`, `IERC721Enumerable` interfaces are part of the [IERC721.sol](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC721/IERC721.sol) file, which document the interfaces.
-- [ERC721](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC721/ERC721.sol) — is the full implementation of ERC721, and the contract you'll most likely be inheriting from.
-- [IERC721Receiver](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC721/IERC721Receiver.sol) — in some cases, it's beneficial to be 100% certain that a contract knows how to handle ERC721 tokens (imagine sending an in-game item to an exchange address that can't send it back!). When using `safeTransferFrom()`, the contract checks to see that the receiver is an `IERC721Receiver`, which implies that it knows how to handle ERC721 tokens. If you're writing a contract that accepts 721 tokens, you'll want to implement this interface.
-- [ERC721Mintable](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC721/ERC721Mintable.sol) — like the ERC20 version, ERC721Mintable allows addresses with the `Minter` role to mint tokens.
-- [ERC721Pausable](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC721/ERC721Pausable.sol) — like the ERC20 version, ERC721Pausable allows addresses with the `Pauser` role to freeze transfers of tokens.
+- The [`IERC721`](api/token/ERC721#ierc721), [`IERC721Metadata`](api/token/ERC721#ierc721metadata), [`IERC721Enumerable`](api/token/ERC721#ierc721enumerable) contracts document the interfaces.
+- [`ERC721`](api/token/ERC721#erc721) — is the full implementation of ERC721, and the contract you'll most likely be inheriting from.
+- [`IERC721Receiver`](api/token/ERC721#ierc721receiver) — in some cases, it's beneficial to be 100% certain that a contract knows how to handle ERC721 tokens (imagine sending an in-game item to an exchange address that can't send it back!). When using [`safeTransferFrom()`](api/token/ERC721#ERC721.safeTransferFrom(address,address,uint256)), the contract checks to see that the receiver is an `IERC721Receiver`, which implies that it knows how to handle ERC721 tokens. If you're writing a contract that accepts ERC721 tokens, you'll want to implement this interface.
+- [`ERC721Mintable`](api/token/ERC721#erc721mintable) — like the ERC20 version, `ERC721Mintable` allows addresses with the `Minter` role to mint tokens.
+- [`ERC721Pausable`](api/token/ERC721#erc721pausable) — like the ERC20 version, `ERC721Pausable` allows addresses with the `Pauser` role to freeze transfers of tokens.
 
 
 We'll use these contracts to tokenize the time of our dogsitters: when a dogsitter wants to sell an hour of their time to watch a dog, they can mint an ERC721 token that represents that hour slot and then sell this token on an exchange. Then they'll go to the owner's house at the right time to watch their doggos.

docs/utilities.md

@@ -0,0 +1,94 @@
+---
+id: utilities
+title: Utilities
+---
+
+OpenZeppelin provides a ton of useful utilities that you can use in your project. Here are some of the more popular ones:
+
+## Cryptography
+
+- [`ECDSA`](api/cryptography#ecdsa) — provides functions for recovering and managing Ethereum account ECDSA signatures:
+  - to use it, declare: `using ECDSA for bytes32;`
+  - signatures are tightly packed, 65 byte `bytes` that look like `{v (1)} {r (32)} {s (32)}`
+    - this is the default from `web3.eth.sign` so you probably don't need to worry about this format
+  - recover the signer using [`myDataHash.recover(signature)`](api/cryptography#ECDSA.recover(bytes32,bytes))
+  - if you are using `eth_personalSign`, the signer will hash your data and then add the prefix `\x19Ethereum Signed Message:\n`, so if you're attempting to recover the signer of an Ethereum signed message hash, you'll want to use [`toEthSignedMessageHash`](api/cryptography#ECDSA.toEthSignedMessageHash(bytes32))
+
+
+Use these functions in combination to verify that a user has signed some information on-chain:
+
+```solidity
+keccack256(
+    abi.encodePacked(
+        someData,
+        moreData
+    )
+)
+.toEthSignedMessageHash()
+.recover(signature)
+```
+
+- [`MerkleProof`](api/cryptography#merkleproof) — provides [`verify`](api/cryptography#MerkleProof.verify(bytes32[],bytes32,bytes32)) for verifying merkle proofs.
+
+
+## Introspection
+
+In Solidity, it's frequently helpful to know whether or not a contract supports an interface you'd like to use. ERC165 is a standard that helps do runtime interface detection. OpenZeppelin provides some helpers, both for implementing ERC165 in your contracts and querying other contracts:
+
+- [`IERC165`](api/introspection#ierc165) — this is the ERC165 interface that defines [`supportsInterface`](api/introspection#IERC165.supportsInterface(bytes4)). When implementing ERC165, you'll conform to this interface.
+- [`ERC165`](api/introspection#erc165) — inherit this contract if you'd like to support interface detection using a lookup table in contract storage. You can register interfaces using [`_registerInterface(bytes4)`](api/introspection#ERC165._registerInterface(bytes4)): check out example usage as part of the ERC721 implementation.
+- [`ERC165Checker`](api/introspection#erc165checker) — ERC165Checker simplifies the process of checking whether or not a contract supports an interface you care about.
+  - include with `using ERC165Checker for address;`
+  - [`myAddress._supportsInterface(bytes4)`](api/introspection#ERC165Checker._supportsInterface(address,bytes4))
+  - [`myAddress._supportsAllInterfaces(bytes4[])`](api/introspection#ERC165Checker._supportsAllInterfaces(address,bytes4[]))
+
+
+```solidity
+contract MyContract {
+    using ERC165Checker for address;
+
+    bytes4 private InterfaceId_ERC721 = 0x80ac58cd;
+
+    /**
+     * @dev transfer an ERC721 token from this contract to someone else
+     */
+    function transferERC721(
+        address token,
+        address to,
+        uint256 tokenId
+    )
+        public
+    {
+        require(token.supportsInterface(InterfaceId_ERC721), "IS_NOT_721_TOKEN");
+        IERC721(token).transferFrom(address(this), to, tokenId);
+    }
+}
+```
+
+## Math
+
+The most popular math related library OpenZeppelin provides is [`SafeMath`](api/math#safemath), which provides mathematical functions that protect your contract from overflows and underflows.
+
+Include the contract with `using SafeMath for uint256;` and then call the functions:
+
+- `myNumber.add(otherNumber)`
+- `myNumber.sub(otherNumber)`
+- `myNumber.div(otherNumber)`
+- `myNumber.mul(otherNumber)`
+- `myNumber.mod(otherNumber)`
+
+Easy!
+
+## Payment
+
+Want to split some payments between multiple people? Maybe you have an app that sends 30% of art purchases to the original creator and 70% of the profits to the current owner; you can build that with [`PaymentSplitter`](api/payment#paymentsplitter)!
+
+In solidity, there are some security concerns with blindly sending money to accounts, since it allows them to execute arbitrary code. You can read up on these security concerns in the [Ethereum Smart Contract Best Practices](https://consensys.github.io/smart-contract-best-practices/) website. One of the ways to fix reentrancy and stalling problems is, instead of immediately sending Ether to accounts that need it, you can use [`PullPayment`](api/payment#pullpayment), which offers an [`_asyncTransfer`](api/payment#PullPayment._asyncTransfer(address,uint256)) function for sending money to something and requesting that they [`withdrawPayments()`](api/payment#PullPayment.withdrawPayments(address%20payable)) it later.
+
+If you want to Escrow some funds, check out [`Escrow`](api/payment#escrow) and [`ConditionalEscrow`](api/payment#conditionalescrow) for governing the release of some escrowed Ether.
+
+### Misc
+
+Want to check if an address is a contract? Use [`Address`](api/utils#address) and [`Address#isContract()`](api/utils#Address.isContract(address)).
+
+Want to keep track of some numbers that increment by 1 every time you want another one? Check out [`Counter`](api/drafts#counter). This is especially useful for creating incremental ERC721 `tokenId`s like we did in the last section.

package.json

@@ -45,6 +45,7 @@
   "homepage": "https://github.com/OpenZeppelin/zeppelin-solidity",
   "devDependencies": {
     "chai": "^4.2.0",
+    "concurrently": "^4.1.0",
     "coveralls": "^3.0.1",
     "eslint": "^4.19.1",
     "eslint-config-standard": "^10.2.1",
@@ -57,11 +58,12 @@
     "ganache-cli": "^6.4.1",
     "ganache-cli-coverage": "https://github.com/frangio/ganache-cli/releases/download/v6.4.1-coverage/ganache-cli-coverage-6.4.1.tgz",
     "micromatch": "^4.0.2",
-    "openzeppelin-docsite": "github:OpenZeppelin/openzeppelin-docsite",
+    "nodemon": "^1.19.0",
+    "openzeppelin-docsite": "github:OpenZeppelin/openzeppelin-docsite#22388b7a891a6fcdd333efef9e4f7f584ae5b826",
     "openzeppelin-test-helpers": "^0.3.2",
     "solhint": "^1.5.0",
     "solidity-coverage": "github:rotcivegaf/solidity-coverage#5875f5b7bc74d447f3312c9c0e9fc7814b482477",
-    "solidity-docgen": "^0.2.0-alpha.0",
+    "solidity-docgen": "github:OpenZeppelin/solidity-docgen#03f42b5e271b1e1c1d0b814b921ecdc086055255",
     "truffle": "^5.0.18"
   }
 }

scripts/docsite.sh

@@ -5,4 +5,11 @@
 set -o errexit
 
 npm run docgen
-npx openzeppelin-docsite-run "$1"
+
+if [ "$1" = start ]; then
+  npx concurrently -n docgen,docsite --no-color \
+    'nodemon -C -w contracts -e sol,md -x npm run docgen' \
+    'openzeppelin-docsite-run start'
+else
+  npx openzeppelin-docsite-run "$1"
+fi