1 files changed, 67 insertions, 12 deletions

diff --git a/docs/contracts.rst b/docs/contracts.rst
index 911bfc0d..dfdcaf18 100644
--- a/docs/contracts.rst
+++ b/docs/contracts.rst
@@ -179,7 +179,7 @@ and the default is ``internal``.
 .. note::
     Everything that is inside a contract is visible to
     all external observers. Making something ``private``
-    only prevents other contract from accessing and modifying
+    only prevents other contracts from accessing and modifying
     the information, but it will still be visible to the
     whole world outside of the blockchain.
 
@@ -195,9 +195,37 @@ return parameter list for functions.
         uint public data;
     }
 
-Other contracts can call ``c.data()`` to retrieve the value of data in state
-storage, but are not able to call ``f``. Contracts derived from ``c`` can call
-``setData`` to alter the value of ``data`` (but only in their own state).
+An other contract ``D`` can call ``c.getData()`` to retrieve the value of data in state
+storage and is not able to call ``f``. Contract ``E`` is derived from ``C`` and can call
+``compute``.
+
+::
+
+    contract C {
+        function f(uint a) private returns(uint b) { return a + 1; }
+        function setData(uint a) { data = a; }
+        function getData() public returns(uint) {return data;}
+        function compute(uint a, uint b) internal returns (uint) { return a+b;}
+        uint private data;
+    }
+
+    contract D {
+        function readData() {
+            C c = new C();
+            local = c.f(7); // error: member "f" is not visible
+            c.setData(3);
+            uint local = c.getData();
+            local = c.compute(3,5); // error: member "compute" is not visible
+        }
+    }
+
+    contract E is C {
+        function g() {
+            C c = new C();
+            uint val = compute(3,5);  // acces to internal member (from derivated to parent contract)
+        }
+    }
+
 
 .. index:: ! accessor;function, ! function;accessor
 
@@ -205,21 +233,38 @@ Accessor Functions
 ==================
 
 The compiler automatically creates accessor functions for
-all public state variables. The contract given below will
-have a function called ``data`` that does not take any
-arguments and returns a uint, the value of the state
+all public state variables. For the contract given below the compiler will
+generate a function called ``data`` that does not take any
+arguments and returns a ``uint``, the value of the state
 variable ``data``. The initialization of state variables can
 be done at declaration.
 
+::
+
+    contract C {
+        uint public data = 42;
+    }
+
+    contract Caller {
+        C c = new C();
+        function f() {
+            uint local = c.data();
+        }
+    }
+
 The accessor functions have external visibility. If the
 symbol is accessed internally (i.e. without ``this.``),
-it is a state variable and if it is accessed externally
-(i.e. with ``this.``), it is a function.
+it is evaluated as state variable and if it is accessed externally
+(i.e. with ``this.``), it is evaluated as function.
 
 ::
 
-    contract Test {
-        uint public data = 42;
+    contract C {
+        uint public data;
+        function x() {
+            data = 3; // internal access
+            uint val = this.data(); // external access
+        }
     }
 
 The next example is a bit more complex:
@@ -380,7 +425,8 @@ Fallback Function
 *****************
 
 A contract can have exactly one unnamed function. This function cannot have
-arguments and is executed on a call to the contract if none of the other
+arguments and cannot return anything.
+It is executed on a call to the contract if none of the other
 functions matches the given function identifier (or if no data was supplied at
 all).
 
@@ -389,6 +435,15 @@ Ether (without data).  In such a context, there is very little gas available to
 the function call (to be precise, 2300 gas), so it is important to make fallback functions as cheap as
 possible.
 
+In particular, the following operations will consume more gas than the stipend provided to a fallback function:
+
+- Writing to storage
+- Creating a contract
+- Calling an external function which consumes a large amount of gas
+- Sending Ether
+
+Please ensure you test your fallback function thoroughly to ensure the execution cost is less than 2300 gas before deploying a contract.
+
 ::
 
     contract Test {