Move control structure related FAQ points

Updates from reviews

clarify returning structs, and move returning arrays and strings from separate section

Further clarifications

Updates from review

Final updates

docs/control-structures.rst

@@ -2,7 +2,7 @@
 Expressions and Control Structures
 ##################################
 
-.. index:: ! parameter, parameter;input, parameter;output
+.. index:: ! parameter, parameter;input, parameter;output, parameter;multiple
 
 Input Parameters and Output Parameters
 ======================================
@@ -32,6 +32,8 @@ something like::
 Input parameters can be used just as any other local variable
 can be used, they can also be assigned to.
 
+.. index:: return array, return string, array, string, array of strings, dynamic array, variably sized array, return struct, struct
+
 Output Parameters
 -----------------
 
@@ -54,12 +56,21 @@ write::
     }
 
 The names of output parameters can be omitted.
-The output values can also be specified using ``return`` statements,
+The return values can be specified using ``return`` statements,
 which are also capable of :ref:`returning multiple values<multi-return>`.
 Return parameters can be used as any other local variable and they
 are zero-initialized; if they are not explicitly
 set, they stay zero.
 
+
+.. note::
+    You cannot return some types from non-internal functions, notably
+    multi-dimensional dynamic arrays and structs. If you enable the
+    new experimental ``ABIEncoderV2`` feature by adding ``pragma experimental
+    ABIEncoderV2;`` to your source file then more types are available, but
+    ``mapping`` types are still limited to inside a single contract and you
+    cannot transfer them.
+
 .. index:: if, else, while, do/while, for, break, continue, return, switch, goto
 
 Control Structures
@@ -120,8 +131,8 @@ External Function Calls
 The expressions ``this.g(8);`` and ``c.g(2);`` (where ``c`` is a contract
 instance) are also valid function calls, but this time, the function
 will be called "externally", via a message call and not directly via jumps.
-Please note that function calls on ``this`` cannot be used in the constructor, as the
-actual contract has not been created yet.
+Please note that function calls on ``this`` cannot be used in the constructor,
+as the actual contract has not been created yet.
 
 Functions of other contracts have to be called externally. For an external call,
 all function arguments have to be copied to memory.
@@ -130,8 +141,10 @@ all function arguments have to be copied to memory.
     A function call from one contract to another does not create its own transaction,
     it is a message call as part of the overall transaction.
 
-When calling functions of other contracts, the amount of Wei sent with the call and
-the gas can be specified with special options ``.value()`` and ``.gas()``, respectively::
+When calling functions of other contracts, you can specify the amount of Wei or gas sent with the call with the special options ``.value()`` and ``.gas()``, respectively. Any Wei you send to the contract is added to the total balance of the contract:
+
+
+::
 
     pragma solidity >=0.4.0 <0.6.0;
 
@@ -400,7 +413,7 @@ In any case, you will get a warning about the outer variable being shadowed.
         }
     }
 
-.. index:: ! exception, ! throw, ! assert, ! require, ! revert
+.. index:: ! exception, ! throw, ! assert, ! require, ! revert, ! errors
 
 .. _assert-and-require:
 

docs/frequently-asked-questions.rst

@@ -38,11 +38,6 @@ has it (which includes `Remix <https://remix.ethereum.org/>`_), then
 ``contractname.kill.sendTransaction({from:eth.coinbase})``, just the same as my
 examples.
 
-Can you return an array or a ``string`` from a solidity function call?
-======================================================================
-
-Yes. See `array_receiver_and_returner.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/60_array_receiver_and_returner.sol>`_.
-
 Is it possible to in-line initialize an array like so: ``string[] myarray = ["a", "b"];``
 =========================================================================================
 
@@ -61,11 +56,6 @@ Example::
         }
     }
 
-Can a contract function return a ``struct``?
-============================================
-
-Yes, but only in ``internal`` function calls or if ``pragma experimental "ABIEncoderV2";`` is used.
-
 If I return an ``enum``, I only get integer values in web3.js. How to get the named values?
 ===========================================================================================
 
@@ -103,15 +93,6 @@ How do structs work?
 
 See `struct_and_for_loop_tester.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/65_struct_and_for_loop_tester.sol>`_.
 
-How do for loops work?
-======================
-
-Very similar to JavaScript. Such as the following example:
-
-``for (uint i = 0; i < a.length; i ++) { a[i] = i; }``
-
-See `struct_and_for_loop_tester.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/65_struct_and_for_loop_tester.sol>`_.
-
 What are some examples of basic string manipulation (``substring``, ``indexOf``, ``charAt``, etc)?
 ==================================================================================================
 
@@ -292,12 +273,6 @@ In this example::
         }
     }
 
-Can a contract function accept a two-dimensional array?
-=======================================================
-
-If you want to pass two-dimensional arrays across non-internal functions,
-you most likely need to use ``pragma experimental "ABIEncoderV2";``.
-
 What is the relationship between ``bytes32`` and ``string``? Why is it that ``bytes32 somevar = "stringliteral";`` works and what does the saved 32-byte hex value mean?
 ========================================================================================================================================================================