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/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.
+ * This implementation is agnostic to the way tokens are created. This means
- * https://eips.ethereum.org/EIPS/eip-20
+ * that a supply mechanism has to be added in a derived contract using `_mint`.
- * Originally based on code by FirstBlood:
+ * For a generic mechanism see `ERC20Mintable`.
- * https://github.com/Firstbloodio/token/blob/master/smart_contract/FirstBloodToken.sol
  *
- * This implementation emits additional Approval events, allowing applications to reconstruct the allowance status for
+ * *For a detailed writeup see our guide [How to implement supply
- * all accounts just by listening to said events. Note that this isn't required by the specification, and other
+ * mechanisms](https://forum.zeppelin.solutions/t/how-to-implement-erc20-supply-mechanisms/226).*
- * compliant implementations may not do it.
+ *
+ * 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,21 +36,40 @@ contract ERC20 is IERC20 {
     uint256 private _totalSupply;
 
     /**
-     * @dev Total number of tokens in existence.
+     * @dev Returns the amount of tokens owned by an account (`owner`). See `IERC20.balanceOf`.
-     */
-    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.
      */
     function balanceOf(address owner) public view returns (uint256) {
         return _balances[owner];
     }
 
+    /**
+     * @dev Moves tokens from the caller's account to a specified recipient
+     * (`to`). See `IERC20.transfer`.
+     *
+     * Requirements
+     *
+     * - `to` cannot be the zero address.
+     */
+    function transfer(address to, uint256 value) public returns (bool) {
+        _transfer(msg.sender, to, value);
+        return true;
+    }
+
+    /**
+     * @dev Configures the amount that a `spender` account is able to spend on
+     * behalf of the caller. See `IERC20.approve`.
+     *
+     * > `approve` can be abused by an untrusted spender.
+     *
+     * Requirements
+     *
+     * - `spender` cannot be the zero address.
+     */
+    function approve(address spender, uint256 value) public returns (bool) {
+        _approve(msg.sender, spender, value);
+        return true;
+    }
+
     /**
      * @dev Function to check the amount of tokens that an owner allowed to a spender.
      * @param owner address The address which owns the funds.
@@ -50,30 +80,6 @@ contract ERC20 is IERC20 {
         return _allowances[owner][spender];
     }
 
-    /**
-     * @dev Transfer token to a specified address.
-     * @param to The address to transfer to.
-     * @param value The amount to be transferred.
-     */
-    function transfer(address to, uint256 value) public returns (bool) {
-        _transfer(msg.sender, to, value);
-        return true;
-    }
-
-    /**
-     * @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.
-     */
-    function approve(address spender, uint256 value) public returns (bool) {
-        _approve(msg.sender, spender, value);
-        return 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,
@@ -118,6 +124,15 @@ contract ERC20 is IERC20 {
         return true;
     }
 
+    /**
+     * @dev Returns the amount of tokens in existence.
+     *
+     * See `IERC20.totalSupply`.
+     */
+    function totalSupply() public view returns (uint256) {
+        return _totalSupply;
+    }
+
     /**
      * @dev Transfer token for a specified addresses.
      * @param from The address to transfer from.

contracts/token/ERC20/IERC20.sol

@@ -1,23 +1,78 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title ERC20 interface
+ * @dev Interface of the ERC20 standard as defined in the EIP. Does not include
- * @dev see https://eips.ethereum.org/EIPS/eip-20
+ * the optional functions; to access them see [ERC20Detailed](#erc20detailed).
  */
 interface IERC20 {
-    function transfer(address to, uint256 value) external returns (bool);
+    /**
-
+     * @dev Returns the amount of tokens owned by an account (`who`).
-    function approve(address spender, uint256 value) external returns (bool);
+     */
-
-    function transferFrom(address from, address to, uint256 value) external returns (bool);
-
-    function totalSupply() external view returns (uint256);
-
     function balanceOf(address who) external view returns (uint256);
 
+    /**
+     * @dev Moves tokens from the caller's account to a specified recipient
+     * (`to`). The amount is specified by `value`.
+     *
+     * Returns a boolean value indicating whether the operation succeeded.
+     *
+     * Emits a `Transfer` event.
+     */
+    function transfer(address to, uint256 value) external returns (bool);
+
+    /**
+     * @dev Configures the amount that a `spender` account is able to spend on
+     * behalf of the caller. The amount is specified by `value`.
+     *
+     * Returns a boolean value indicating whether the operation succeeded.
+     *
+     * See `allowance` and `transferFrom`.
+     *
+     * > 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 value) external returns (bool);
+
+    /**
+     * @dev Returns the current allowance that an `owner` has set for a `spender`.
+     *
+     * This value is updated when either `approve` or `transferFrom` are called.
+     */
     function allowance(address owner, address spender) external view returns (uint256);
 
+    /**
+     * @dev Moves tokens from one account (`from`) to another (`to`). The
+     * caller must have remaining allowance from the owner (see `approve` and
+     * `allowance`). If this operation succeeds, the transferred amount
+     * (`value`) is deducted from the caller's allowance.
+     *
+     * Returns a boolean value indicating whether the operation succeeded.
+
+     * Emits a `Transfer` event.
+     */
+    function transferFrom(address from, address to, uint256 value) external returns (bool);
+
+    /**
+     * @dev Returns the amount of tokens in existence.
+     */
+    function totalSupply() external view returns (uint256);
+
+    /**
+     * @dev Emitted when tokens are moved from one account (`from`) to anoter (`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,33 @@
 ---
 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](../../learn-about-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.