doc: add a section about input parameters and output parameters

1 files changed, 56 insertions, 1 deletions

diff --git a/docs/control-structures.rst b/docs/control-structures.rst
index f57e7936..015e5526 100644
--- a/docs/control-structures.rst
+++ b/docs/control-structures.rst
@@ -2,6 +2,53 @@
 Expressions and Control Structures
 ##################################
 
+.. index:: ! parameter, parameter;input, parameter;output
+
+Input Parameters and Output Parameters
+======================================
+
+Like in Javascript and in C, functions may take parameters as input;
+unlike in Javascript and C, they may also return arbitrary number of
+parameters as output.
+
+Input Parameters
+----------------
+
+The input parameters are declared type followed
+by name (though unused input parameters do not need names).
+For example, suppose we want our contract to
+accept one kind of external calls with two integers, we would write
+something like::
+
+    contract Simple {
+        function taker(uint _a, uint _b) {
+            // do something with _a and _b.
+        }
+    }
+
+Output Parameters
+-----------------
+
+The output parameters can be declared with the same syntax after the
+``returns`` keyword. For example, suppose we wished to return two results:
+the sum and the product of the two given integers, then we would
+write::
+
+    contract Simple {
+        function arithmetics(uint _a, uint _b) returns (uint o_sum, uint o_product) {
+            o_sum = _a + _b;
+            o_product = _a * _b;
+        }
+    }
+
+The names of output parameters can be omitted.
+Return parameters are initialized to zero; if they are not explicitly
+set, they stay to be zero.
+
+Input parameters and output parameters can be used as expressions in
+the function body.  There, they are also usable in the left-hand side
+of assignment.
+
 .. index:: if, else, while, do/while, for, break, continue, return, switch, goto
 
 Control Structures
@@ -16,7 +63,15 @@ Parentheses can *not* be omitted for conditionals, but curly brances can be omit
 around single-statement bodies.
 
 Note that there is no type conversion from non-boolean to boolean types as
-there is in C and JavaScript, so ``if (1) { ... }`` is *not* valid Solidity.
+there is in C and JavaScript, so ``if (1) { ... }`` is *not* valid
+Solidity.
+
+Returning Multiple Values
+-------------------------
+
+When a function has multiple output parameters, ``return (v0, v1, ...,
+vn)`` can return multiple values.  The number of components must be
+the same as the number of output parameters.
 
 .. index:: ! function;call, function;internal, function;external