From 135c55c4d0e51277d56b2d23f26c91cc46e3df57 Mon Sep 17 00:00:00 2001
From: Alex Beregszaszi <alex@rtfs.hu>
Date: Wed, 13 Sep 2017 09:49:19 +0100
Subject: [PATCH] Overhaul contract creation section in the documentation (add
 reference to remix and web3.js)

---
 docs/contracts.rst | 48 ++++++++++------------------------------------
 1 file changed, 10 insertions(+), 38 deletions(-)

diff --git a/docs/contracts.rst b/docs/contracts.rst
index a1a446658..3bd6f6a81 100644
--- a/docs/contracts.rst
+++ b/docs/contracts.rst
@@ -16,51 +16,23 @@ inaccessible.
 Creating Contracts
 ******************
 
-Contracts can be created "from outside" or from Solidity contracts.
+Contracts can be created "from outside" via Ethereum transactions or from within Solidity contracts.
+
+IDEs, such as `Remix <https://remix.ethereum.org/>`_, make the creation process seamless using UI elements.
+
+Creating contracts programatically on Ethereum is best done via using the JavaScript API `web3.js <https://github.com/etherem/web3.js>`_.
+As of today it has a method called `web3.eth.Contract <https://web3js.readthedocs.io/en/1.0/web3-eth-contract.html#new-contract>`_
+to facilitate contract creation.
+
 When a contract is created, its constructor (a function with the same
 name as the contract) is executed once.
-
 A constructor is optional. Only one constructor is allowed, and this means
 overloading is not supported.
 
-From ``web3.js``, i.e. the JavaScript
-API, this is done as follows::
-
-    // Need to specify some source including contract name for the data param below
-    var source = "contract CONTRACT_NAME { function CONTRACT_NAME(uint a, uint b) {} }";
-
-    // The json abi array generated by the compiler
-    var abiArray = [
-        {
-            "inputs":[
-                {"name":"x","type":"uint256"},
-                {"name":"y","type":"uint256"}
-            ],
-            "type":"constructor"
-        },
-        {
-            "constant":true,
-            "inputs":[],
-            "name":"x",
-            "outputs":[{"name":"","type":"bytes32"}],
-            "type":"function"
-        }
-    ];
-
-    var MyContract_ = web3.eth.contract(source);
-    MyContract = web3.eth.contract(MyContract_.CONTRACT_NAME.info.abiDefinition);
-    // deploy new contract
-    var contractInstance = MyContract.new(
-        10,
-        11,
-        {from: myAccount, gas: 1000000}
-    );
-
 .. index:: constructor;arguments
 
-Internally, constructor arguments are passed after the code of
-the contract itself, but you do not have to care about this
-if you use ``web3.js``.
+Internally, constructor arguments are passed :ref:`ABI encoded <ABI>` after the code of
+the contract itself, but you do not have to care about this if you use ``web3.js``.
 
 If a contract wants to create another contract, the source code
 (and the binary) of the created contract has to be known to the creator.