improve blocks and functions docs

docs/index.rst

@@ -33,6 +33,7 @@ Usage
    quick_start
    language
    recipes
+   questions
 
 
 

docs/language.rst

@@ -405,19 +405,25 @@ Functions can be defined in Tealish in the following forms::
 - Functions must have ``return`` just before ``end``.
 - Functions must be defined at the end of programs or Blocks. There can be no other statements after function definitions apart from other function definitions.
 
-Examples::
+Examples:
 
-    func get_balance(account_idx: int, asset_id: int) int:
-        int balance
-        if asset_id == 0:
-            balance = balance(account_idx) - min_balance(account_idx)
-        else:
-            _, balance = asset_holding_get(AssetBalance, account_idx, asset_id)
-        end
-        return balance
-    end
+.. literalinclude:: ./sources/language/functions.tl
+
+.. _blocks:
+
+Blocks
+------
 
-    func checks():
-        assert(app_local_get(0, "x") > 7)
-        assert(app_local_get(0, "y") > 6)
+Blocks can be defined in Tealish in the following forms::
+
+    block {block_name}:
+    {Statements}
     end
+
+- Variables are scoped by blocks and functions.
+- Blocks should end with an exit statement.
+
+Examples:
+
+.. literalinclude:: ./sources/language/blocks.tl
+

docs/questions.rst

@@ -0,0 +1,26 @@
+.. _questions:
+
+FAQ
+===
+
+What is the difference between `Block` and `Func (Function)`?
+-------------------------------------------------------------
+Similar to high level programming languages, :ref:`functions` get some inputs and return some outputs.
+It simply allows using the a code block again and again.
+:ref:`blocks` are helpful in managing the application flow.
+
+Technically, TEAL uses
+`scratchspace <https://developer.algorand.org/docs/get-details/dapps/avm/teal/#storing-and-loading-from-scratchspace>`_
+to temporarily store values. Tealish automatically manages scratchspace usage and assigns a slot to each variables.
+:ref:`blocks` and :ref:`functions` have different slot spaces. When a function is called, inputs are copied to reserved
+slot spaces of the function and outputs are copied to reserved slot spaces of the caller (block, function or program).
+
+Does Tealish has stateful and stateless mode?
+---------------------------------------------
+No, Tealish doesn't have modes. The author is responsible for using appropriate `opcodes <https://developer.algorand.org/docs/get-details/dapps/avm/teal/opcodes/>`_.
+
+
+
+Can I use subroutines in Tealish?
+---------------------------------
+Yes, :ref:`functions` are subroutines under the hood.

docs/recipes.rst

@@ -37,13 +37,6 @@ allows handling integer overflows.
    :emphasize-lines: 7-9
    :linenos:
 
-
-Can I use subroutines in Tealish?
----------------------------------
-
-Yes, :ref:`functions` are subroutines under the hood.
-
-
 Optimize the generated TEAL code partially
 ------------------------------------------
 

docs/sources/language/blocks.tl

@@ -0,0 +1,22 @@
+block main:
+    int sender = Txn.Sender
+    pay_to_user()
+    exit(1)
+
+    func pay_to_user(amount: int):
+        # Function can use variables defined in the outer blocks.
+        pay(sender, amount)
+        return
+    end
+    exit(0)
+end
+
+func pay(receiver: bytes, amount: int):
+    inner_txn:
+        TypeEnum: Pay
+        Receiver: receiver
+        Amount: amount
+        Fee: 0
+    end
+    return
+end

docs/sources/language/functions.tl

@@ -0,0 +1,14 @@
+func get_balance(account_idx: int, asset_id: int) int:
+    int balance
+    if asset_id == 0:
+        balance = balance(account_idx) - min_balance(account_idx)
+    else:
+        _, balance = asset_holding_get(AssetBalance, account_idx, asset_id)
+    end
+    return balance
+end
+
+func checks():
+    assert(app_local_get(0, "x") > 7)
+    assert(app_local_get(0, "y") > 6)
+end