New guides (#1792)

* Improved tokens guide, add ERC777.

* Fix typo.

* Add release schedule and api stability.

* Add erc20 supply guide.

* Revamp get started

* Add Solidity version to examples

* Update access control guide.

* Add small disclaimer to blog guides

* Update tokens guide.

* Update docs/access-control.md

Co-Authored-By: Francisco Giordano <frangio.1@gmail.com>

* Update docs/access-control.md

Co-Authored-By: Francisco Giordano <frangio.1@gmail.com>

* Update docs/access-control.md

Co-Authored-By: Francisco Giordano <frangio.1@gmail.com>

* Apply suggestions from code review

Co-Authored-By: Francisco Giordano <frangio.1@gmail.com>

* Apply suggestions from code review

Co-Authored-By: Francisco Giordano <frangio.1@gmail.com>

* Documentation: Typos and add npm init -y to setup instructions (#1793)

* Fix typos in GameItem ERC721 sample contract

* Add npm init -y to create package.json

* Address review comments.

(cherry picked from commit 852e11c2db)

contracts/token/ERC20/ERC20Pausable.sol

@@ -5,7 +5,11 @@ import "../../lifecycle/Pausable.sol";
 
 /**
  * @title Pausable token
- * @dev ERC20 modified with pausable transfers.
+ * @dev ERC20 with pausable transfers and allowances.
+ *
+ * Useful if you want to e.g. stop trades until the end of a crowdsale, or have
+ * an emergency switch for freezing all token transfers in the event of a large
+ * bug.
  */
 contract ERC20Pausable is ERC20, Pausable {
     function transfer(address to, uint256 value) public whenNotPaused returns (bool) {

contracts/token/ERC20/README.md

@@ -19,13 +19,16 @@ sections:
 
 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).*
+*For an overview of ERC20 tokens and a walkthrough on how to create a token contract read our [ERC20 guide](../../tokens#erc20).*
 
-There a few core contracts that implement the behavior specified in the EIP: `IERC20`, `ERC20`, `ERC20Detailed`.
+There a few core contracts that implement the behavior specified in the EIP:
+ - `IERC20`: the interface all ERC20 implementations should conform to
+ - `ERC20`: the base implementation of the ERC20 interface
+ - `ERC20Detailed`: includes the `name()`, `symbol()` and `decimals()` optional standard extension to the base interface
 
-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`),
+Additionally there are multiple custom 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.

contracts/token/ERC20/TokenTimelock.sol

@@ -3,9 +3,14 @@ pragma solidity ^0.5.0;
 import "./SafeERC20.sol";
 
 /**
- * @title TokenTimelock
- * @dev TokenTimelock is a token holder contract that will allow a
- * beneficiary to extract the tokens after a given release time.
+ * @dev A token holder contract that will allow a beneficiary to extract the
+ * tokens after a given release time.
+ *
+ * Useful for simple vesting schedules like "advisors get all of their tokens
+ * after 1 year".
+ *
+ * For a more complete vesting schedule, see
+ * [`TokenVesting`](api/drafts#tokenvesting).
  */
 contract TokenTimelock {
     using SafeERC20 for IERC20;

contracts/token/ERC721/README.md

@@ -26,12 +26,17 @@ This set of interfaces, contracts, and utilities are all related to the [ERC721
 
 *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`.
+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`.
+
+Additionally, `IERC721Receiver` can be used to prevent tokens from becoming forever locked in contracts. Imagine sending an in-game item to an exchange address that can't send it back!. When using `safeTransferFrom()`, the token 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 needs to receive `ERC721` tokens, you'll want to include this interface.
+
+Finally, some custom extensions are also included:
+- `ERC721Mintable` — like the ERC20 version, this allows certain addresses to mint new tokens
+- `ERC721Pausable` — like the ERC20 version, this allows addresses to freeze transfers of tokens
 
 > This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/token/ERC777/README.md

@@ -12,6 +12,8 @@ sections:
 
 This set of interfaces and contracts are all related to the [ERC777 token standard](https://eips.ethereum.org/EIPS/eip-777).
 
+*For an overview of ERC777 tokens and a walkthrough on how to create a token contract read our [ERC777 guide](../../tokens#erc20).*
+
 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`.