Merge pull request #5571 from ethereum/develop

Version 0.5.1

1 files changed, 124 insertions, 10 deletions

diff --git a/docs/contracts.rst b/docs/contracts.rst
index c1c51e56..98419430 100644
--- a/docs/contracts.rst
+++ b/docs/contracts.rst
@@ -485,6 +485,110 @@ value types and strings.
 Functions
 *********
 
+.. _function-parameters-return-variables:
+
+Function Parameters and Return Variables
+========================================
+
+As in JavaScript, functions may take parameters as input. Unlike in JavaScript
+and C, functions may also return an arbitrary number of values as output.
+
+Function Parameters
+-------------------
+
+Function parameters are declared the same way as variables, and the name of
+unused parameters can be omitted.
+
+For example, if you want your contract to accept one kind of external call
+with two integers, you would use something like::
+
+    pragma solidity >=0.4.16 <0.6.0;
+
+    contract Simple {
+        uint sum;
+        function taker(uint _a, uint _b) public {
+            sum = _a + _b;
+        }
+    }
+
+Function parameters can be used as any other local variable and they can also be assigned to.
+
+.. note::
+
+  An :ref:`external function<external-function-calls>` cannot accept a
+  multi-dimensional array as an input
+  parameter. This functionality is possible if you enable the new
+  experimental ``ABIEncoderV2`` feature by adding ``pragma experimental ABIEncoderV2;`` to your source file.
+
+  An :ref:`internal function<external-function-calls>` can accept a
+  multi-dimensional array without enabling the feature.
+
+.. index:: return array, return string, array, string, array of strings, dynamic array, variably sized array, return struct, struct
+
+Return Variables
+----------------
+
+Function return variables are declared with the same syntax after the
+``returns`` keyword.
+
+For example, suppose you want to return two results: the sum and the product of
+two integers passed as function parameters, then you use something like::
+
+    pragma solidity >=0.4.16 <0.6.0;
+
+    contract Simple {
+        function arithmetic(uint _a, uint _b)
+            public
+            pure
+            returns (uint o_sum, uint o_product)
+        {
+            o_sum = _a + _b;
+            o_product = _a * _b;
+        }
+    }
+
+The names of return variables can be omitted.
+Return variables can be used as any other local variable and they
+are initialized with their :ref:`default value <default-value>` and have that value unless explicitly set.
+
+You can either explicitly assign to return variables and
+then leave the function using ``return;``,
+or you can provide return values
+(either a single or :ref:`multiple ones<multi-return>`) directly with the ``return``
+statement::
+
+    pragma solidity >=0.4.16 <0.6.0;
+
+    contract Simple {
+        function arithmetic(uint _a, uint _b)
+            public
+            pure
+            returns (uint o_sum, uint o_product)
+        {
+            return (_a + _b, _a * _b);
+        }
+    }
+
+This form is equivalent to first assigning values to the
+return variables and then using ``return;`` to leave the function.
+
+.. 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.
+
+.. _multi-return:
+
+Returning Multiple Values
+-------------------------
+
+When a function has multiple return types, the statement ``return (v0, v1, ..., vn) can be used to return multiple values.
+vn)`` can return multiple values.  The number of components must be
+the same as the number of return types.
+
 .. index:: ! view function, function;view
 
 .. _view-functions:
@@ -569,6 +673,20 @@ In addition to the list of state modifying statements explained above, the follo
         }
     }
 
+Pure functions are able to use the `revert()` and `require()` functions to revert
+potential state changes when an :ref:`error occurs <assert-and-require>`.
+
+Reverting a state change is not considered a "state modification", as only changes to the
+state made previously in code that did not have the ``view`` or ``pure`` restriction
+are reverted and that code has the option to catch the ``revert`` and not pass it on.
+
+This behaviour is also in line with the ``STATICCALL`` opcode.
+
+.. warning::
+  It is not possible to prevent functions from reading the state at the level
+  of the EVM, it is only possible to prevent them from writing to the state
+  (i.e. only ``view`` can be enforced at the EVM level, ``pure`` can not).
+
 .. note::
   Prior to version 0.5.0, the compiler did not use the ``STATICCALL`` opcode
   for ``pure`` functions.
@@ -577,13 +695,8 @@ In addition to the list of state modifying statements explained above, the follo
   By using  ``STATICCALL`` for ``pure`` functions, modifications to the
   state are prevented on the level of the EVM.
 
-.. warning::
-  It is not possible to prevent functions from reading the state at the level
-  of the EVM, it is only possible to prevent them from writing to the state
-  (i.e. only ``view`` can be enforced at the EVM level, ``pure`` can not).
-
-.. warning::
-  Before version 0.4.17 the compiler did not enforce that ``pure`` is not reading the state.
+.. note::
+  Prior to version 0.4.17 the compiler did not enforce that ``pure`` is not reading the state.
   It is a compile-time type check, which can be circumvented doing invalid explicit conversions
   between contract types, because the compiler can verify that the type of the contract does
   not do state-changing operations, but it cannot check that the contract that will be called
@@ -932,14 +1045,15 @@ Additional Resources for Understanding Events
 Inheritance
 ***********
 
-Solidity supports multiple inheritance by copying code including polymorphism.
+Solidity supports multiple inheritance including polymorphism.
 
 All function calls are virtual, which means that the most derived function
-is called, except when the contract name is explicitly given.
+is called, except when the contract name is explicitly given or the
+``super`` keyword is used.
 
 When a contract inherits from other contracts, only a single
 contract is created on the blockchain, and the code from all the base contracts
-is copied into the created contract.
+is compiled into the created contract.
 
 The general inheritance system is very similar to
 `Python's <https://docs.python.org/3/tutorial/classes.html#inheritance>`_,