Merge pull request #5771 from ethereum/docs-split-operators

[DOCS] Split operators involving LValues into new doc

2 files changed, 48 insertions, 47 deletions

diff --git a/docs/types.rst b/docs/types.rst
index 1fb15bdc..ea45b7d7 100644
--- a/docs/types.rst
+++ b/docs/types.rst
@@ -81,53 +81,7 @@ each ``_KeyType``, recursively. For example with a mapping:
   Mappings are not iterable, but it is possible to implement a data structure
   on top of them. For an example, see `iterable mapping <https://github.com/ethereum/dapp-bin/blob/master/library/iterable_mapping.sol>`_.
 
-.. index:: assignment, ! delete, lvalue
-
-Operators Involving LValues
-===========================
-
-If ``a`` is an LValue (i.e. a variable or something that can be assigned to), the following operators are available as shorthands:
-
-``a += e`` is equivalent to ``a = a + e``. The operators ``-=``, ``*=``, ``/=``, ``%=``, ``|=``, ``&=`` and ``^=`` are defined accordingly. ``a++`` and ``a--`` are equivalent to ``a += 1`` / ``a -= 1`` but the expression itself still has the previous value of ``a``. In contrast, ``--a`` and ``++a`` have the same effect on ``a`` but return the value after the change.
-
-delete
-------
-
-``delete a`` assigns the initial value for the type to ``a``. I.e. for integers it is
-equivalent to ``a = 0``, but it can also be used on arrays, where it assigns a dynamic
-array of length zero or a static array of the same length with all elements set to their
-initial value. ``delete a[x]`` deletes the item at index ``x`` of the array and leaves
-all other elements and the length of the array untouched. This especially means that it leaves
-a gap in the array. If you plan to remove items, a mapping is probably a better choice.
-
-For structs, it assigns a struct with all members reset. In other words, the value of ``a`` after ``delete a`` is the same as if ``a`` would be declared without assignment, with the following caveat:
-
-``delete`` has no effect on mappings (as the keys of mappings may be arbitrary and are generally unknown). So if you delete a struct, it will reset all members that are not mappings and also recurse into the members unless they are mappings. However, individual keys and what they map to can be deleted: If ``a`` is a mapping, then ``delete a[x]`` will delete the value stored at ``x``.
-
-It is important to note that ``delete a`` really behaves like an assignment to ``a``, i.e. it stores a new object in ``a``.
-This distinction is visible when ``a`` is reference variable: It will only reset ``a`` itself, not the
-value it referred to previously.
-
-::
-
-    pragma solidity >=0.4.0 <0.6.0;
-
-    contract DeleteExample {
-        uint data;
-        uint[] dataArray;
-
-        function f() public {
-            uint x = data;
-            delete x; // sets x to 0, does not affect data
-            delete data; // sets data to 0, does not affect x
-            uint[] storage y = dataArray;
-            delete dataArray; // this sets dataArray.length to zero, but as uint[] is a complex object, also
-            // y is affected which is an alias to the storage object
-            // On the other hand: "delete y" is not valid, as assignments to local variables
-            // referencing storage objects can only be made from existing storage objects.
-            assert(y.length == 0);
-        }
-    }
+.. include:: types/operators.rst
 
 .. index:: ! type;conversion, ! cast
 
diff --git a/docs/types/operators.rst b/docs/types/operators.rst
new file mode 100644
index 00000000..9851f214
--- /dev/null
+++ b/docs/types/operators.rst
@@ -0,0 +1,47 @@
+.. index:: assignment, ! delete, lvalue
+
+Operators Involving LValues
+===========================
+
+If ``a`` is an LValue (i.e. a variable or something that can be assigned to), the following operators are available as shorthands:
+
+``a += e`` is equivalent to ``a = a + e``. The operators ``-=``, ``*=``, ``/=``, ``%=``, ``|=``, ``&=`` and ``^=`` are defined accordingly. ``a++`` and ``a--`` are equivalent to ``a += 1`` / ``a -= 1`` but the expression itself still has the previous value of ``a``. In contrast, ``--a`` and ``++a`` have the same effect on ``a`` but return the value after the change.
+
+delete
+------
+
+``delete a`` assigns the initial value for the type to ``a``. I.e. for integers it is
+equivalent to ``a = 0``, but it can also be used on arrays, where it assigns a dynamic
+array of length zero or a static array of the same length with all elements set to their
+initial value. ``delete a[x]`` deletes the item at index ``x`` of the array and leaves
+all other elements and the length of the array untouched. This especially means that it leaves
+a gap in the array. If you plan to remove items, a mapping is probably a better choice.
+
+For structs, it assigns a struct with all members reset. In other words, the value of ``a`` after ``delete a`` is the same as if ``a`` would be declared without assignment, with the following caveat:
+
+``delete`` has no effect on mappings (as the keys of mappings may be arbitrary and are generally unknown). So if you delete a struct, it will reset all members that are not mappings and also recurse into the members unless they are mappings. However, individual keys and what they map to can be deleted: If ``a`` is a mapping, then ``delete a[x]`` will delete the value stored at ``x``.
+
+It is important to note that ``delete a`` really behaves like an assignment to ``a``, i.e. it stores a new object in ``a``.
+This distinction is visible when ``a`` is reference variable: It will only reset ``a`` itself, not the
+value it referred to previously.
+
+::
+
+    pragma solidity >=0.4.0 <0.6.0;
+
+    contract DeleteExample {
+        uint data;
+        uint[] dataArray;
+
+        function f() public {
+            uint x = data;
+            delete x; // sets x to 0, does not affect data
+            delete data; // sets data to 0, does not affect x
+            uint[] storage y = dataArray;
+            delete dataArray; // this sets dataArray.length to zero, but as uint[] is a complex object, also
+            // y is affected which is an alias to the storage object
+            // On the other hand: "delete y" is not valid, as assignments to local variables
+            // referencing storage objects can only be made from existing storage objects.
+            assert(y.length == 0);
+        }
+    }