From 936bade46f3f6f44c3d0c0cc079a7de77104e2b9 Mon Sep 17 00:00:00 2001
From: Yoichi Hirai <i@yoichihirai.com>
Date: Wed, 23 Nov 2016 14:47:58 +0100
Subject: [PATCH 1/3] doc: add a section about input parameters and output
 parameters

---
 docs/control-structures.rst | 57 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 56 insertions(+), 1 deletion(-)

diff --git a/docs/control-structures.rst b/docs/control-structures.rst
index f57e7936e..015e55265 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
 

From 0599a14954aa0c22c992ae4585010a97cce63ca1 Mon Sep 17 00:00:00 2001
From: Yoichi Hirai <i@yoichihirai.com>
Date: Thu, 24 Nov 2016 12:22:57 +0100
Subject: [PATCH 2/3] docs: cross-reference returning multiple values

---
 docs/control-structures.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/control-structures.rst b/docs/control-structures.rst
index 015e55265..4879a10e2 100644
--- a/docs/control-structures.rst
+++ b/docs/control-structures.rst
@@ -42,6 +42,9 @@ write::
     }
 
 The names of output parameters can be omitted.
+The output values can also be specified using ``return`` statements.
+The ``return`` statements are also capable of returning multiple
+values, see :ref:`multi-return`.
 Return parameters are initialized to zero; if they are not explicitly
 set, they stay to be zero.
 
@@ -66,6 +69,8 @@ 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.
 
+.. _multi-return:
+
 Returning Multiple Values
 -------------------------
 

From fed50403ffdf16806fd4bc0aee1587e22576d4d0 Mon Sep 17 00:00:00 2001
From: Yoichi Hirai <i@yoichihirai.com>
Date: Thu, 24 Nov 2016 18:32:45 +0100
Subject: [PATCH 3/3] docs: cleaning references to C; smoothing parameter
 syntax description

---
 docs/control-structures.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/control-structures.rst b/docs/control-structures.rst
index 4879a10e2..974a093f2 100644
--- a/docs/control-structures.rst
+++ b/docs/control-structures.rst
@@ -7,15 +7,15 @@ Expressions and Control Structures
 Input Parameters and Output Parameters
 ======================================
 
-Like in Javascript and in C, functions may take parameters as input;
+As in Javascript, 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).
+The input parameters are declared the same way as variables are. As an
+exception, unused parameters can omit the variable name.
 For example, suppose we want our contract to
 accept one kind of external calls with two integers, we would write
 something like::
@@ -57,7 +57,7 @@ of assignment.
 Control Structures
 ===================
 
-Most of the control structures from C or JavaScript are available in Solidity
+Most of the control structures from JavaScript are available in Solidity
 except for ``switch`` and ``goto``. So
 there is: ``if``, ``else``, ``while``, ``do``, ``for``, ``break``, ``continue``, ``return``, ``? :``, with
 the usual semantics known from C or JavaScript.