Merge pull request #11616 from ethereum/issue-8191-yul

Test yul code blocks in documentation.

docs/internals/optimizer.rst

@@ -519,7 +519,7 @@ compact again at the end.
 ExpressionSplitter
 ^^^^^^^^^^^^^^^^^^
 
-The expression splitter turns expressions like ``add(mload(x), mul(mload(y), 0x20))``
+The expression splitter turns expressions like ``add(mload(0x123), mul(mload(0x456), 0x20))``
 into a sequence of declarations of unique variables that are assigned sub-expressions
 of that expression so that each function call has only variables or literals
 as arguments.
@@ -529,9 +529,9 @@ The above would be transformed into
 .. code-block:: yul
 
     {
-        let _1 := mload(y)
+        let _1 := mload(0x123)
         let _2 := mul(_1, 0x20)
-        let _3 := mload(x)
+        let _3 := mload(0x456)
         let z := add(_3, _2)
     }
 
@@ -633,7 +633,7 @@ The SSA transform converts this snippet to the following:
 
     {
         let a_1 := 1
-        a := a_1
+        let a := a_1
         let a_2 := mload(a_1)
         a := a_2
         let a_3 := sload(a_2)
@@ -1186,16 +1186,18 @@ The SSA transform rewrites
 
 .. code-block:: yul
 
-    a := E
+    let a := calldataload(0)
     mstore(a, 1)
 
 to
 
 .. code-block:: yul
 
-    let a_1 := E
-    a := a_1
+    let a_1 := calldataload(0)
+    let a := a_1
     mstore(a_1, 1)
+    let a_2 := calldataload(0x20)
+    a := a_2
 
 The problem is that instead of ``a``, the variable ``a_1`` is used
 whenever ``a`` was referenced. The SSA transform changes statements
@@ -1204,9 +1206,11 @@ snippet is turned into
 
 .. code-block:: yul
 
-    a := E
+    let a := calldataload(0)
     let a_1 := a
     mstore(a_1, 1)
+    a := calldataload(0x20)
+    let a_2 := a
 
 This is a very simple equivalence transform, but when we now run the
 Common Subexpression Eliminator, it will replace all occurrences of ``a_1``

docs/yul.rst

@@ -198,7 +198,8 @@ has to be specified after a colon:
 
 .. code-block:: yul
 
-    let x := and("abc":uint32, add(3:uint256, 2:uint256))
+    // This will not compile (u32 and u256 type not implemented yet)
+    let x := and("abc":u32, add(3:u256, 2:u256))
 
 
 Function Calls
@@ -212,10 +213,9 @@ they have to be assigned to local variables.
 
 .. code-block:: yul
 
+    function f(x, y) -> a, b { /* ... */ }
     mstore(0x80, add(mload(0x80), 3))
-    // Here, the user-defined function `f` returns
-    // two values. The definition of the function
-    // is missing from the example.
+    // Here, the user-defined function `f` returns two values.
     let x, y := f(1, mload(0))
 
 For built-in functions of the EVM, functional expressions
@@ -271,9 +271,10 @@ that returns multiple values.
 
 .. code-block:: yul
 
+    // This will not compile (u32 and u256 type not implemented yet)
     {
-        let zero:uint32 := 0:uint32
-        let v:uint256, t:uint32 := f()
+        let zero:u32 := 0:u32
+        let v:u256, t:u32 := f()
         let x, y := g()
     }
 
@@ -314,7 +315,7 @@ you need multiple alternatives.
 
 .. code-block:: yul
 
-    if eq(value, 0) { revert(0, 0) }
+    if lt(calldatasize(), 4) { revert(0, 0) }
 
 The curly braces for the body are required.