Initial ERC777 docstrings.

contracts/token/ERC20/ERC20.sol

@@ -16,12 +16,12 @@ import "../../math/SafeMath.sol";
  * 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`.
@@ -35,6 +35,15 @@ contract ERC20 is IERC20 {
 
     uint256 private _totalSupply;
 
+    /**
+     * @dev Returns the amount of tokens in existence.
+     *
+     * See `IERC20.totalSupply`.
+     */
+    function totalSupply() public view returns (uint256) {
+        return _totalSupply;
+    }
+
     /**
      * @dev Returns the amount of tokens owned by an account (`owner`). See `IERC20.balanceOf`.
      */
@@ -124,15 +133,6 @@ 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

@@ -5,6 +5,11 @@ pragma solidity ^0.5.0;
  * the optional functions; to access them see [ERC20Detailed](#erc20detailed).
  */
 interface IERC20 {
+    /**
+     * @dev Returns the amount of tokens in existence.
+     */
+    function totalSupply() external view returns (uint256);
+
     /**
      * @dev Returns the amount of tokens owned by an account (`who`).
      */
@@ -58,11 +63,6 @@ interface IERC20 {
      */
     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`).
      *

contracts/token/ERC777/IERC777.sol

@@ -1,15 +1,41 @@
 pragma solidity ^0.5.0;
 
 /**
- * @title ERC777 token interface
- * @dev See https://eips.ethereum.org/EIPS/eip-777
+ * @dev Interface of the ERC777Tken standard as defined in the EIP.
  */
 interface IERC777 {
+    /**
+     * @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 a specified
+     * recipient (`to`).
+     *
+     * If send or receive hooks are registered for the caller and receiver,
+     * the corresponding functions will be called with `data` and empty
+     * `operatorData`. See `IERC777Sender` and `IERC777Recipient`.
+     *
+     * Emits a `Sent` event.
+     */
+    function send(address to, 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.
+     */
+    function burn(uint256 amount, bytes calldata data) external;
+
     function authorizeOperator(address operator) external;
 
     function revokeOperator(address operator) external;
 
-    function send(address to, uint256 amount, bytes calldata data) external;
 
     function operatorSend(
         address from,
@@ -19,8 +45,6 @@ interface IERC777 {
         bytes calldata operatorData
     ) external;
 
-    function burn(uint256 amount, bytes calldata data) external;
-
     function operatorBurn(
         address from,
         uint256 amount,
@@ -34,8 +58,6 @@ interface IERC777 {
 
     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);

contracts/token/ERC777/README.md

@@ -0,0 +1,19 @@
+---
+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).
+
+*For a walkthrough on how to create an ERC777 token read our [ERC777 guide](../../learn-about-tokens.md#erc777).*
+
+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`.