5 files changed, 78 insertions, 11 deletions
diff --git a/docs/assembly.rst b/docs/assembly.rst
index cf9bf840..705cd1b8 100644
--- a/docs/assembly.rst
+++ b/docs/assembly.rst
@@ -647,6 +647,11 @@ Solidity manages memory in a very simple way: There is a "free memory pointer"
 at position ``0x40`` in memory. If you want to allocate memory, just use the memory
 from that point on and update the pointer accordingly.
 
+The first 64 bytes of memory can be used as "scratch space" for short-term
+allocation. The 32 bytes after the free memory pointer (i.e. starting at ``0x60``)
+is meant to be zero permanently and is used as the initial value for
+empty dynamic memory arrays.
+
 Elements in memory arrays in Solidity always occupy multiples of 32 bytes (yes, this is
 even true for ``byte[]``, but not for ``bytes`` and ``string``). Multi-dimensional memory
 arrays are pointers to memory arrays. The length of a dynamic array is stored at the
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 1bcaed7c..6717a8b9 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -55,8 +55,8 @@ However, if you are making a larger change, please consult with the `Solidity De
 focused on compiler and language development instead of language use) first.
 
 
-Finally, please make sure you respect the `coding standards
-<https://raw.githubusercontent.com/ethereum/cpp-ethereum/develop/CodingStandards.txt>`_
+Finally, please make sure you respect the `coding style
+<https://raw.githubusercontent.com/ethereum/solidity/develop/CODING_STYLE.md>`_
 for this project. Also, even though we do CI testing, please test your code and
 ensure that it builds locally before submitting a pull request.
 
@@ -170,6 +170,57 @@ and re-run the test. It will now pass again:
     Please choose a name for the contract file, that is self-explainatory in the sense of what is been tested, e.g. ``double_variable_declaration.sol``.
     Do not put more than one contract into a single file. ``isoltest`` is currently not able to recognize them individually.
 
+
+Running the Fuzzer via AFL
+==========================
+
+Fuzzing is a technique that runs programs on more or less random inputs to find exceptional execution
+states (segmentation faults, exceptions, etc). Modern fuzzers are clever and do a directed search
+inside the input. We have a specialized binary called ``solfuzzer`` which takes source code as input
+and fails whenever it encounters an internal compiler error, segmentation fault or similar, but
+does not fail if e.g. the code contains an error. This way, internal problems in the compiler
+can be found by fuzzing tools.
+
+We mainly use `AFL <http://lcamtuf.coredump.cx/afl/>`_ for fuzzing. You need to download and
+build AFL manually. Next, build Solidity (or just the ``solfuzzer`` binary) with AFL as your compiler:
+
+::
+
+    cd build
+    # if needed
+    make clean
+    cmake .. -DCMAKE_C_COMPILER=path/to/afl-gcc -DCMAKE_CXX_COMPILER=path/to/afl-g++
+    make solfuzzer
+
+Next, you need some example source files. This will make it much easer for the fuzzer
+to find errors. You can either copy some files from the syntax tests or extract test files
+from the documentation or the other tests:
+
+::
+
+    mkdir /tmp/test_cases
+    cd /tmp/test_cases
+    # extract from tests:
+    path/to/solidity/scripts/isolate_tests.py path/to/solidity/test/libsolidity/SolidityEndToEndTest.cpp
+    # extract from documentation:
+    path/to/solidity/scripts/isolate_tests.py path/to/solidity/docs docs
+
+The AFL documentation states that the corpus (the initial input files) should not be
+too large. The files themselves should not be larger than 1 kB and there should be
+at most one input file per functionality, so better start with a small number of
+input files. There is also a tool called ``afl-cmin`` that can trim input files
+that result in similar behaviour of the binary.
+
+Now run the fuzzer (the ``-m`` extends the size of memory to 60 MB):
+
+::
+
+    afl-fuzz -m 60 -i /tmp/test_cases -o /tmp/fuzzer_reports -- /path/to/solfuzzer
+
+The fuzzer will create source files that lead to failures in ``/tmp/fuzzer_reports``.
+Often it finds many similar source files that produce the same error. You can
+use the tool ``scripts/uniqueErrors.sh`` to filter out the unique errors.
+
 Whiskers
 ========
 
diff --git a/docs/control-structures.rst b/docs/control-structures.rst
index 46e076e5..40070a20 100644
--- a/docs/control-structures.rst
+++ b/docs/control-structures.rst
@@ -284,10 +284,12 @@ Solidity internally allows tuple types, i.e. a list of objects of potentially di
         }
 
         function g() public {
-            // Declares and assigns the variables. Specifying the type explicitly is not possible.
-            var (x, b, y) = f();
-            // Assigns to a pre-existing variable.
-            (x, y) = (2, 7);
+            // Variables declared with type
+            uint x;
+            bool b;
+            uint y;
+            // Tuple values can be assigned to these pre-existing variables
+            (x, b, y) = f();
             // Common trick to swap values -- does not work for non-value storage types.
             (x, y) = (y, x);
             // Components can be left out (also for variable declarations).
diff --git a/docs/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst
index 56f0fe3e..84b1fff8 100644
--- a/docs/introduction-to-smart-contracts.rst
+++ b/docs/introduction-to-smart-contracts.rst
@@ -326,7 +326,13 @@ EVM bytecode and executed. The output of this execution is
 permanently stored as the code of the contract.
 This means that in order to create a contract, you do not
 send the actual code of the contract, but in fact code that
-returns that code.
+returns that code when executed.
+
+.. note::
+  While a contract is being created, its code is still empty.
+  Because of that, you should not call back into the
+  contract under construction until its constructor has
+  finished executing.
 
 .. index:: ! gas, ! gas price
 
diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst
index 01154854..20400aa2 100644
--- a/docs/miscellaneous.rst
+++ b/docs/miscellaneous.rst
@@ -64,12 +64,15 @@ The position of ``data[4][9].b`` is at ``keccak256(uint256(9) . keccak256(uint25
 Layout in Memory
 ****************
 
-Solidity reserves three 256-bit slots:
+Solidity reserves four 32 byte slots:
 
--  0 - 64: scratch space for hashing methods
-- 64 - 96: currently allocated memory size (aka. free memory pointer)
+- ``0x00`` - ``0x3f``: scratch space for hashing methods
+- ``0x40`` - ``0x5f``: currently allocated memory size (aka. free memory pointer)
+- ``0x60`` - ``0x7f``: zero slot
 
-Scratch space can be used between statements (ie. within inline assembly).
+Scratch space can be used between statements (ie. within inline assembly). The zero slot
+is used as initial value for dynamic memory arrays and should never be written to
+(the free memory pointer points to ``0x80`` initially).
 
 Solidity always places new objects at the free memory pointer and memory is never freed (this might change in the future).