Merge pull request #4496 from ethereum/faq-reorg-contracts

Move contract related FAQ points

docs/contracts.rst

@@ -26,8 +26,8 @@ Creating contracts programmatically on Ethereum is best done via using the JavaS
 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 declared with the
+When a contract is created, its constructor_  (a function declared with the ``constructor`` keyword) is executed once.
-``constructor`` keyword) is executed once.
+
 A constructor is optional. Only one constructor is allowed, and this means
 overloading is not supported.
 
@@ -261,7 +261,37 @@ it is evaluated as a state variable.  If it is accessed externally
         }
     }
 
-The next example is a bit more complex:
+If you have a `public` state variable of array type, then you can only retrieve
+single elements of the array via the generated getter function. This mechanism
+exists to avoid high gas costs when returning an entire array. You can use
+arguments to specify which individual element to return, for example
+``data(0)``. If you want to return an entire array in one call, then you need
+to write a function, for example:
+
+::
+
+  pragma solidity ^0.4.0;
+  contract arrayExample {
+    // public state variable
+    uint[] public myArray;
+
+    // Getter function generated by the compiler
+    /*
+    function myArray(uint i) returns (uint) {
+        return myArray[i];
+    }
+    */
+
+    // function that returns entire array
+    function getArray() returns (uint[] memory) {
+        return myArray;
+    }
+  }
+
+Now you can use ``getArray()`` to retrieve the entire array, instead of
+``myArray(i)``, which returns a single element per call.
+
+The next example is more complex:
 
 ::
 
@@ -276,16 +306,16 @@ The next example is a bit more complex:
         mapping (uint => mapping(bool => Data[])) public data;
     }
 
-It will generate a function of the following form::
+It generates a function of the following form. The mapping in the struct is omitted
+because there is no good way to provide the key for the mapping:
+
+::
 
     function data(uint arg1, bool arg2, uint arg3) public returns (uint a, bytes3 b) {
         a = data[arg1][arg2][arg3].a;
         b = data[arg1][arg2][arg3].b;
     }
 
-Note that the mapping in the struct is omitted because there
-is no good way to provide the key for the mapping.
-
 .. index:: ! function;modifier
 
 .. _modifiers:
@@ -994,12 +1024,26 @@ virtual method lookup.
 
 .. index:: ! constructor
 
+.. _constructor:
+
 Constructors
 ============
-A constructor is an optional function declared with the ``constructor`` keyword which is executed upon contract creation.
-Constructor functions can be either ``public`` or ``internal``. If there is no constructor, the contract will assume the
-default constructor: ``contructor() public {}``.
 
+A constructor is an optional function declared with the ``constructor`` keyword
+which is executed upon contract creation, and where you can run contract
+initialisation code.
+
+Before the constructor code is executed, state variables are initialised to
+their specified value if you initialise them inline, or zero if you do not.
+
+After the final code of the contract is returned. The final deployment of
+the code costs additional gas linear to the length of the code. If you did not
+supply enough gas to initiate the state variables declared in the constructor,
+then an "out of gas" exception is generated.
+
+Constructor functions can be either ``public`` or ``internal``. If there is no
+constructor, the contract will assume the default constructor, which is
+equivalent to ``constructor() public {}``. For example:
 
 ::
 

docs/frequently-asked-questions.rst

@@ -238,13 +238,6 @@ The key point is that the calling contract needs to know about the function it i
 See `ping.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/45_ping.sol>`_
 and `pong.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/45_pong.sol>`_.
 
-Get contract to do something when it is first mined
-===================================================
-
-Use the constructor. Anything inside it will be executed when the contract is first mined.
-
-See `replicator.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/50_replicator.sol>`_.
-
 How do you create 2-dimensional arrays?
 =======================================
 
@@ -410,28 +403,6 @@ Is it possible to return an array of strings (``string[]``) from a Solidity func
 
 Not yet, as this requires two levels of dynamic arrays (``string`` is a dynamic array itself).
 
-If you issue a call for an array, it is possible to retrieve the whole array? Or must you write a helper function for that?
-===========================================================================================================================
-
-The automatic :ref:`getter function<getter-functions>`  for a public state variable of array type only returns
-individual elements. If you want to return the complete array, you have to
-manually write a function to do that.
-
-
-What could have happened if an account has storage value(s) but no code?  Example: http://test.ether.camp/account/5f740b3a43fbb99724ce93a879805f4dc89178b5
-==========================================================================================================================================================
-
-The last thing a constructor does is returning the code of the contract.
-The gas costs for this depend on the length of the code and it might be
-that the supplied gas is not enough. This situation is the only one
-where an "out of gas" exception does not revert changes to the state,
-i.e. in this case the initialisation of the state variables.
-
-https://github.com/ethereum/wiki/wiki/Subtleties
-
-After a successful CREATE operation's sub-execution, if the operation returns x, 5 * len(x) gas is subtracted from the remaining gas before the contract is created. If the remaining gas is less than 5 * len(x), then no gas is subtracted, the code of the created contract becomes the empty string, but this is not treated as an exceptional condition - no reverts happen.
-
-
 What does the following strange check do in the Custom Token contract?
 ======================================================================