Merge pull request #5962 from ethereum/docs-modular-example

[DOCS] Create modular example

docs/examples/modular.rst

@@ -0,0 +1,57 @@
+.. index:: contract;modular, modular contract
+
+*****************
+Modular Contracts
+*****************
+
+A modular approach to building your contracts helps you prevent overflow risks
+and unexpected tokens. In the example below, the contract uses the ``move`` method
+of the ``Balances`` :ref:`library <libraries>` to check that balances sent between
+addresses match what you expect.
+
+::
+
+    pragma solidity >=0.4.22 <0.6.0;
+
+    library Balances {
+        function move(mapping(address => uint256) storage balances, address from, address to, uint amount) internal {
+            require(balances[from] >= amount);
+            require(balances[to] + amount >= balances[to]);
+            balances[from] -= amount;
+            balances[to] += amount;
+        }
+    }
+
+    contract Token {
+        mapping(address => uint256) balances;
+        using Balances for *;
+        mapping(address => mapping (address => uint256)) allowed;
+
+        event Transfer(address from, address to, uint amount);
+        event Approval(address owner, address spender, uint amount);
+
+        function balanceOf(address tokenOwner) public view returns (uint balance) {
+            return balances[tokenOwner];
+        }
+        function transfer(address to, uint amount) public returns (bool success) {
+            balances.move(msg.sender, to, amount);
+            emit Transfer(msg.sender, to, amount);
+            return true;
+
+        }
+
+        function transferFrom(address from, address to, uint amount) public returns (bool success) {
+            require(allowed[from][msg.sender] >= amount);
+            allowed[from][msg.sender] -= amount;
+            balances.move(from, to, amount);
+            emit Transfer(from, to, amount);
+            return true;
+        }
+
+        function approve(address spender, uint tokens) public returns (bool success) {
+            require(allowed[msg.sender][spender] == 0, "");
+            allowed[msg.sender][spender] = tokens;
+            emit Approval(msg.sender, spender, tokens);
+            return true;
+        }
+    }

docs/solidity-by-example.rst

@@ -3,8 +3,11 @@ Solidity by Example
 ###################
 
 .. include:: examples/voting.rst
+
 .. include:: examples/blind-auction.rst
 
 .. include:: examples/safe-remote.rst
 
 .. include:: examples/micropayment.rst
+
+.. include:: examples/modular.rst