1 files changed, 54 insertions, 10 deletions

diff --git a/docs/contracts.rst b/docs/contracts.rst
index 862ec54d..5742de06 100644
--- a/docs/contracts.rst
+++ b/docs/contracts.rst
@@ -24,8 +24,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
-``constructor`` keyword) is executed once.
+When a contract is created, its constructor_  (a function declared with the ``constructor`` keyword) is executed once.
+
 A constructor is optional. Only one constructor is allowed, and this means
 overloading is not supported.
 
@@ -262,7 +262,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:
 
 ::
 
@@ -277,16 +307,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:
@@ -990,12 +1020,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:
 
 ::